From 0b74ad0a641f28d9d3da5353e98372d87078bd9d Mon Sep 17 00:00:00 2001 From: Riccardo Mazzarini Date: Tue, 5 Dec 2023 12:33:57 +0100 Subject: refactor(api): complete conversion from `Dictionary` to `Dict(opts)` (#26365) --- runtime/lua/vim/_meta/api.lua | 20 ++++++++++---------- runtime/lua/vim/_meta/api_keysets.lua | 22 ++++++++++++++++++++++ 2 files changed, 32 insertions(+), 10 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 49269ba631..4ad0a2e791 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -151,7 +151,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- `nvim_buf_lines_event`. Else the first notification --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. ---- @param opts table Optional parameters. +--- @param opts vim.api.keyset.buf_attach Optional parameters. --- • on_lines: Lua callback invoked on change. Return `true` to detach. Args: --- • the string "lines" --- • buffer handle @@ -284,7 +284,7 @@ function vim.api.nvim_buf_del_var(buffer, name) end --- Deletes the buffer. See `:bwipeout` --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @param opts table Optional parameters. Keys: +--- @param opts vim.api.keyset.buf_delete Optional parameters. Keys: --- • force: Force deletion and ignore unsaved changes. --- • unload: Unloaded only, do not delete. See `:bunload` function vim.api.nvim_buf_delete(buffer, opts) end @@ -307,7 +307,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id ---- @param opts table Optional parameters. Keys: +--- @param opts vim.api.keyset.get_extmark Optional parameters. Keys: --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead --- of id, true if omitted @@ -440,7 +440,7 @@ function vim.api.nvim_buf_get_option(buffer, name) end --- @param start_col integer Starting column (byte offset) on first line --- @param end_row integer Last line index, inclusive --- @param end_col integer Ending column (byte offset) on last line, exclusive ---- @param opts table Optional parameters. Currently unused. +--- @param opts vim.api.keyset.empty Optional parameters. Currently unused. --- @return string[] function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end @@ -626,7 +626,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- @param name string Mark name --- @param line integer Line number --- @param col integer Column/row number ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return boolean function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end @@ -675,7 +675,7 @@ function vim.api.nvim_buf_set_var(buffer, name, value) end --- @param src_id integer --- @param line integer --- @param chunks any[] ---- @param opts table +--- @param opts vim.api.keyset.empty --- @return integer function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end @@ -1241,7 +1241,7 @@ function vim.api.nvim_get_keymap(mode) end --- Marks are (1,0)-indexed. `api-indexing` --- --- @param name string Mark name ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return any[] function vim.api.nvim_get_mark(name, opts) end @@ -1439,7 +1439,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- virtual terminal having the intended size. --- --- @param buffer integer the buffer to use (expected to be empty) ---- @param opts table Optional parameters. +--- @param opts vim.api.keyset.open_term Optional parameters. --- • on_input: Lua callback for input sent, i e keypresses in --- terminal mode. Note: keypresses are sent raw as they would --- be to the pty master end. For instance, a carriage return @@ -1602,7 +1602,7 @@ function vim.api.nvim_out_write(str) end --- Doesn't check the validity of command arguments. --- --- @param str string Command line string to parse. Cannot contain "\n". ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return table function vim.api.nvim_parse_cmd(str, opts) end @@ -1685,7 +1685,7 @@ function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end --- inserted in the buffer. Ignored for `cmdline-completion`. --- @param finish boolean Finish the completion and dismiss the popup menu. Implies --- {insert}. ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end --- Sets the current buffer. diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index f69e5a92c7..6a3e574455 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -3,6 +3,19 @@ -- DO NOT EDIT error('Cannot require a meta file') +--- @class vim.api.keyset.buf_attach +--- @field on_lines? function +--- @field on_bytes? function +--- @field on_changedtick? function +--- @field on_detach? function +--- @field on_reload? function +--- @field utf_sizes? boolean +--- @field preview? boolean + +--- @class vim.api.keyset.buf_delete +--- @field force? boolean +--- @field unload? boolean + --- @class vim.api.keyset.clear_autocmds --- @field buffer? integer --- @field event? any @@ -74,6 +87,8 @@ error('Cannot require a meta file') --- @class vim.api.keyset.echo_opts --- @field verbose? boolean +--- @class vim.api.keyset.empty + --- @class vim.api.keyset.eval_statusline --- @field winid? integer --- @field maxwidth? integer @@ -124,6 +139,10 @@ error('Cannot require a meta file') --- @class vim.api.keyset.get_commands --- @field builtin? boolean +--- @class vim.api.keyset.get_extmark +--- @field details? boolean +--- @field hl_name? boolean + --- @class vim.api.keyset.get_extmarks --- @field limit? integer --- @field details? boolean @@ -196,6 +215,9 @@ error('Cannot require a meta file') --- @field desc? string --- @field replace_keycodes? boolean +--- @class vim.api.keyset.open_term +--- @field on_input? function + --- @class vim.api.keyset.option --- @field scope? string --- @field win? integer -- cgit From e057b38e7037808b3593fb1035794595b4e4a45e Mon Sep 17 00:00:00 2001 From: Emanuel Date: Wed, 6 Dec 2023 16:56:04 +0100 Subject: fix(json): allow objects with empty keys #25564 Problem: Empty string is a valid JSON key, but json_decode() treats an object with empty key as ":help msgpack-special-dict". #20757 :echo json_decode('{"": "1"}') {'_TYPE': [], '_VAL': [['', '1']]} Note: vim returns `{'': '1'}`. Solution: Allow empty string as an object key. Note that we still (currently) disallow empty keys in object_to_vim() (since 7c01d5ff9286d262097484c680e3a4eab49e2911): https://github.com/neovim/neovim/blob/f64e4b43e1191ff30d902730f752875aa55682ce/src/nvim/api/private/converter.c#L333-L334 Fix #20757 Co-authored-by: Justin M. Keyes --- runtime/lua/vim/_meta/vimfn.lua | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 05e5b2b871..7234b813b6 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -4678,8 +4678,7 @@ function vim.fn.join(list, sep) end --- Vim value. In the following cases it will output --- |msgpack-special-dict|: --- 1. Dictionary contains duplicate key. ---- 2. Dictionary contains empty key. ---- 3. String contains NUL byte. Two special dictionaries: for +--- 2. String contains NUL byte. Two special dictionaries: for --- dictionary and for string will be emitted in case string --- with NUL byte was a dictionary key. --- @@ -5922,7 +5921,6 @@ function vim.fn.msgpackdump(list, type) end --- are binary strings). --- 2. String with NUL byte inside. --- 3. Duplicate key. ---- 4. Empty key. --- ext |List| with two values: first is a signed integer --- representing extension type. Second is --- |readfile()|-style list of strings. -- cgit From 2613ba5000d4c0d9b15e2eec2d2b97615575925e Mon Sep 17 00:00:00 2001 From: Gregory Anders Date: Tue, 5 Dec 2023 10:01:32 -0800 Subject: feat(defaults): enable 'termguicolors' by default when supported by terminal Enable 'termguicolors' automatically when Nvim can detect that truecolor is supported by the host terminal. If $COLORTERM is set to "truecolor" or "24bit", or the terminal's terminfo entry contains capabilities for Tc, RGB, or setrgbf and setrgbb, then we assume that the terminal supports truecolor. Otherwise, the terminal is queried (using both XTGETTCAP and SGR + DECRQSS). If the terminal's response to these queries (if any) indicates that it supports truecolor, then 'termguicolors' is enabled. --- runtime/lua/vim/_meta/options.lua | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index d2bdab4d28..5e65ca6b1b 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6941,6 +6941,10 @@ vim.go.tbidi = vim.go.termbidi --- attributes instead of "cterm" attributes. `guifg` --- Requires an ISO-8613-3 compatible terminal. --- +--- Nvim will automatically attempt to determine if the host terminal +--- supports 24-bit color and will enable this option if it does +--- (unless explicitly disabled by the user). +--- --- @type boolean vim.o.termguicolors = false vim.o.tgc = vim.o.termguicolors -- cgit From 619407eb548c7df56bc99b945338e9446f846fbb Mon Sep 17 00:00:00 2001 From: Raphael Date: Thu, 14 Dec 2023 16:08:00 +0800 Subject: feat(nvim_open_term): convert LF => CRLF (#26384) Problem: Unlike termopen(), nvim_open_term() PTYs do not carriage-return the cursor on newline ("\n") input. nvim --clean :let chan_id = nvim_open_term(1, {}) :call chansend(chan_id, ["here", "are", "some", "lines"]) Actual behavior: here are some lines Expected behaviour: here are some lines Solution: Add `force_crlf` option, and enable it by default. --- runtime/lua/vim/_meta/api.lua | 2 ++ runtime/lua/vim/_meta/api_keysets.lua | 1 + 2 files changed, 3 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 4ad0a2e791..231e1c3404 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1446,6 +1446,8 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- is sent as a "\r", not as a "\n". `textlock` applies. It --- is possible to call `nvim_chan_send()` directly in the --- callback however. ["input", term, bufnr, data] +--- • force_crlf: (boolean, default true) Convert "\n" to +--- "\r\n". --- @return integer function vim.api.nvim_open_term(buffer, opts) end diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 6a3e574455..f64cdb8afd 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -217,6 +217,7 @@ error('Cannot require a meta file') --- @class vim.api.keyset.open_term --- @field on_input? function +--- @field force_crlf? boolean --- @class vim.api.keyset.option --- @field scope? string -- cgit From 97bea3163a3fe50359e7f6ffda747e28974a818a Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Wed, 13 Dec 2023 12:00:11 +0000 Subject: feat(lsp): more annotations --- runtime/lua/vim/_meta/vvars.lua | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 runtime/lua/vim/_meta/vvars.lua (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua new file mode 100644 index 0000000000..059ef04203 --- /dev/null +++ b/runtime/lua/vim/_meta/vvars.lua @@ -0,0 +1,23 @@ +--- @meta _ + +-- TODO(lewis6991): generate this and `:help vim-variable` + +--- @class vim.v +--- The count given for the last Normal mode command. Can be used +--- to get the count before a mapping. Read-only. Example: +--- ```vim +--- :map _x :echo "the count is " .. v:count +--- ``` +--- Note: The is required to remove the line range that you +--- get when typing ':' after a count. +--- When there are two counts, as in "3d2w", they are multiplied, +--- just like what happens in the command, "d6w" for the example. +--- Also used for evaluating the 'formatexpr' option. +--- @field count integer +--- +--- Line number for the 'foldexpr' |fold-expr|, 'formatexpr', +--- 'indentexpr' and 'statuscolumn' expressions, tab page number +--- for 'guitablabel' and 'guitabtooltip'. Only valid while one of +--- these expressions is being evaluated. Read-only when in the |sandbox|. +--- @field lnum integer +vim.v = ... -- cgit From 165e5ececc25ce2d705efdd8ee6c8406884bf898 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 15 Dec 2023 06:42:29 +0800 Subject: vim-patch:17dca3cb97cd (#26584) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit runtime(doc): grammar & typo fixes closes: vim/vim#13654 https://github.com/vim/vim/commit/17dca3cb97cdd7835e334b990565c8c0b93b1284 Co-authored-by: Dominique Pellé --- runtime/lua/vim/_meta/vimfn.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 7234b813b6..ead5d8d13b 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -6156,9 +6156,9 @@ function vim.fn.prevnonblank(lnum) end --- Date: Tue, 15 Aug 2023 18:47:14 +0800 Subject: feat(ui): completeopt support popup like vim --- runtime/lua/vim/_meta/api.lua | 10 ++++++++++ runtime/lua/vim/_meta/api_keysets.lua | 3 +++ runtime/lua/vim/_meta/options.lua | 4 ++++ runtime/lua/vim/_meta/vimfn.lua | 2 ++ 4 files changed, 19 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 231e1c3404..c8afbd58dd 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -773,6 +773,16 @@ function vim.api.nvim_command(command) end --- @return string function vim.api.nvim_command_output(command) end +--- Set info for the completion candidate index. if the info was shown in a +--- window, then the window and buffer ids are returned for further +--- customization. If the text was not shown, an empty dict is returned. +--- +--- @param index integer the completion candidate index +--- @param opts vim.api.keyset.complete_set Optional parameters. +--- • info: (string) info text. +--- @return table +function vim.api.nvim_complete_set(index, opts) end + --- Create or get an autocommand group `autocmd-groups`. --- To get an existing group id, do: --- diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index f64cdb8afd..4ec8b03d30 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -68,6 +68,9 @@ error('Cannot require a meta file') --- @class vim.api.keyset.cmd_opts --- @field output? boolean +--- @class vim.api.keyset.complete_set +--- @field info? string + --- @class vim.api.keyset.context --- @field types? any[] diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 5e65ca6b1b..c908d7ae54 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -1061,6 +1061,10 @@ vim.bo.cfu = vim.bo.completefunc --- select one from the menu. Only works in combination with --- "menu" or "menuone". --- +--- popup Show extra information about the currently selected +--- completion in a popup window. Only works in combination +--- with "menu" or "menuone". Overrides "preview". +--- --- @type string vim.o.completeopt = "menu,preview" vim.o.cot = vim.o.completeopt diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index ead5d8d13b..59d9836688 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -1024,6 +1024,8 @@ function vim.fn.complete_check() end --- no item is selected when using the or --- keys) --- inserted Inserted string. [NOT IMPLEMENTED YET] +--- preview_winid Info floating preview window id. +--- preview_bufnr Info floating preview buffer id. --- --- *complete_info_mode* --- mode values are: -- cgit From 69f5f0e20e81ef3b6cb5ea011eda024e6e277acf Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Sat, 16 Dec 2023 15:03:22 +0100 Subject: vim-patch:82f19734bfcb runtime(doc): remove deprecation warning for gdefault Deprecated can be misunderstood as being slated for removal; slightly change wording to be clearer. https://github.com/vim/vim/commit/82f19734bfcbddbaee8d5d837f7b7a7119366020 Co-authored-by: dundargoc --- runtime/lua/vim/_meta/options.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index c908d7ae54..f52cea9900 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -2595,9 +2595,9 @@ vim.go.fs = vim.go.fsync --- :s///g subst. one subst. all --- :s///gg subst. all subst. one --- ---- DEPRECATED: Setting this option may break plugins that are not aware ---- of this option. Also, many users get confused that adding the /g flag ---- has the opposite effect of that it normally does. +--- NOTE: Setting this option may break plugins that rely on the default +--- behavior of the 'g' flag. This will also make the 'g' flag have the +--- opposite effect of that documented in `:s_g`. --- --- @type boolean vim.o.gdefault = false -- cgit From 8fb7419d7c5e2df3b792d18fa56f973088e69be2 Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Sat, 16 Dec 2023 11:18:45 -0600 Subject: refactor: only reload colorscheme if &bg changed (#26598) Currently, setting &bg at all re-initializes highlights and reloads the active colorscheme, even if the actual value of &bg has not changed. With https://github.com/neovim/neovim/pull/26595 this causes a regression since &bg is set unconditionally based on the value detected from the terminal. Instead, only reload the colorscheme if the actual value of &bg has changed. --- runtime/lua/vim/_meta/options.lua | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index f52cea9900..e63c5bb972 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -191,7 +191,7 @@ vim.go.awa = vim.go.autowriteall --- See `:hi-normal` if you want to set the background color explicitly. --- *g:colors_name* --- When a color scheme is loaded (the "g:colors_name" variable is set) ---- setting 'background' will cause the color scheme to be reloaded. If +--- changing 'background' will cause the color scheme to be reloaded. If --- the color scheme adjusts to the value of 'background' this will work. --- However, if the color scheme sets 'background' itself the effect may --- be undone. First delete the "g:colors_name" variable when needed. @@ -203,13 +203,9 @@ vim.go.awa = vim.go.autowriteall --- : set background=dark --- :endif --- ``` ---- When this option is set, the default settings for the highlight groups +--- When this option is changed, the default settings for the highlight groups --- will change. To use other settings, place ":highlight" commands AFTER --- the setting of the 'background' option. ---- This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file ---- to select the colors for syntax highlighting. After changing this ---- option, you must load syntax.vim again to see the result. This can be ---- done with ":syntax on". --- --- @type string vim.o.background = "dark" -- cgit From 428edcde7068ab44040e19b43343741e5ca59770 Mon Sep 17 00:00:00 2001 From: Amanda Graven Date: Tue, 28 Nov 2023 21:05:33 +0100 Subject: feat(api): add forward and back mouse buttons --- runtime/lua/vim/_meta/api.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index c8afbd58dd..c8c3e1c3af 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1375,7 +1375,7 @@ function vim.api.nvim_input(keys) end --- processed soon by the event loop. --- --- @param button string Mouse button: one of "left", "right", "middle", "wheel", ---- "move". +--- "move", "x1", "x2". --- @param action string For ordinary buttons, one of "press", "drag", "release". --- For the wheel, one of "up", "down", "left", "right". --- Ignored for "move". -- cgit From 693aea0e9e1032aee85d56c1a3f33e0811dbdc18 Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Tue, 19 Dec 2023 06:29:13 +0100 Subject: docs: small fixes (#26448) Co-authored-by: Gregory Anders <8965202+gpanders@users.noreply.github.com> Co-authored-by: Jordan Mandel --- runtime/lua/vim/_meta/options.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index e63c5bb972..6b7cfa79b3 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -1049,11 +1049,11 @@ vim.bo.cfu = vim.bo.completefunc --- completion in the preview window. Only works in --- combination with "menu" or "menuone". --- ---- noinsert Do not insert any text for a match until the user selects +--- noinsert Do not insert any text for a match until the user selects --- a match from the menu. Only works in combination with --- "menu" or "menuone". No effect if "longest" is present. --- ---- noselect Do not select a match in the menu, force the user to +--- noselect Do not select a match in the menu, force the user to --- select one from the menu. Only works in combination with --- "menu" or "menuone". --- -- cgit From e8d3c4cccb9d362952a09216a5a114ee6d024c14 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Wed, 20 Dec 2023 16:34:17 +0000 Subject: feat: generate types and docs for v variables --- runtime/lua/vim/_meta/vvars.lua | 765 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 757 insertions(+), 8 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index 059ef04203..e3b89aeff7 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -1,23 +1,772 @@ --- @meta _ - --- TODO(lewis6991): generate this and `:help vim-variable` +-- THIS FILE IS GENERATED +-- DO NOT EDIT +error('Cannot require a meta file') --- @class vim.v +vim.v = ... + +--- The command line arguments Vim was invoked with. This is a +--- list of strings. The first item is the Vim command. +--- See `v:progpath` for the command with full path. +--- @type string[] +vim.v.argv = ... + +--- Argument for evaluating 'formatexpr' and used for the typed +--- character when using in an abbreviation `:map-`. +--- It is also used by the `InsertCharPre` and `InsertEnter` events. +--- @type any +vim.v.char = ... + +--- The name of the character encoding of a file to be converted. +--- Only valid while evaluating the 'charconvert' option. +--- @type string +vim.v.charconvert_from = ... + +--- The name of the character encoding of a file after conversion. +--- Only valid while evaluating the 'charconvert' option. +--- @type string +vim.v.charconvert_to = ... + +--- The extra arguments ("++p", "++enc=", "++ff=") given to a file +--- read/write command. This is set before an autocommand event +--- for a file read/write command is triggered. There is a +--- leading space to make it possible to append this variable +--- directly after the read/write command. Note: "+cmd" isn't +--- included here, because it will be executed anyway. +--- @type string[] +vim.v.cmdarg = ... + +--- Set like v:cmdarg for a file read/write command. When a "!" +--- was used the value is 1, otherwise it is 0. Note that this +--- can only be used in autocommands. For user commands `` +--- can be used. +--- @type any +vim.v.cmdbang = ... + +--- The current locale setting for collation order of the runtime +--- environment. This allows Vim scripts to be aware of the +--- current locale encoding. Technical: it's the value of +--- LC_COLLATE. When not using a locale the value is "C". +--- This variable can not be set directly, use the `:language` +--- command. +--- See `multi-lang`. +--- @type string +vim.v.collate = ... + +--- Dictionary containing the most recent `complete-items` after +--- `CompleteDone`. Empty if the completion failed, or after +--- leaving and re-entering insert mode. +--- Note: Plugins can modify the value to emulate the builtin +--- `CompleteDone` event behavior. +--- @type any +vim.v.completed_item = ... + --- The count given for the last Normal mode command. Can be used --- to get the count before a mapping. Read-only. Example: +--- --- ```vim ---- :map _x :echo "the count is " .. v:count +--- :map _x :echo "the count is " .. v:count --- ``` +--- --- Note: The is required to remove the line range that you --- get when typing ':' after a count. --- When there are two counts, as in "3d2w", they are multiplied, --- just like what happens in the command, "d6w" for the example. --- Also used for evaluating the 'formatexpr' option. ---- @field count integer +--- @type integer +vim.v.count = ... + +--- Just like "v:count", but defaults to one when no count is +--- used. +--- @type integer +vim.v.count1 = ... + +--- The current locale setting for characters of the runtime +--- environment. This allows Vim scripts to be aware of the +--- current locale encoding. Technical: it's the value of +--- LC_CTYPE. When not using a locale the value is "C". +--- This variable can not be set directly, use the `:language` +--- command. +--- See `multi-lang`. +--- @type any +vim.v.ctype = ... + +--- Normally zero. When a deadly signal is caught it's set to +--- one. When multiple signals are caught the number increases. +--- Can be used in an autocommand to check if Vim didn't +--- terminate normally. +--- Example: +--- +--- ```vim +--- :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif +--- ``` --- ---- Line number for the 'foldexpr' |fold-expr|, 'formatexpr', +--- Note: if another deadly signal is caught when v:dying is one, +--- VimLeave autocommands will not be executed. +--- @type integer +vim.v.dying = ... + +--- Number of screen cells that can be used for an `:echo` message +--- in the last screen line before causing the `hit-enter-prompt`. +--- Depends on 'showcmd', 'ruler' and 'columns'. You need to +--- check 'cmdheight' for whether there are full-width lines +--- available above the last line. +--- @type integer +vim.v.echospace = ... + +--- Last given error message. +--- Modifiable (can be set). +--- Example: +--- +--- ```vim +--- let v:errmsg = "" +--- silent! next +--- if v:errmsg != "" +--- " ... handle error +--- ``` +--- @type string +vim.v.errmsg = ... + +--- Errors found by assert functions, such as `assert_true()`. +--- This is a list of strings. +--- The assert functions append an item when an assert fails. +--- The return value indicates this: a one is returned if an item +--- was added to v:errors, otherwise zero is returned. +--- To remove old results make it empty: +--- +--- ```vim +--- let v:errors = [] +--- ``` +--- +--- If v:errors is set to anything but a list it is made an empty +--- list by the assert function. +--- @type any +vim.v.errors = ... + +--- Dictionary of event data for the current `autocommand`. Valid +--- only during the event lifetime; storing or passing v:event is +--- invalid! Copy it instead: +--- +--- ```vim +--- au TextYankPost * let g:foo = deepcopy(v:event) +--- ``` +--- +--- Keys vary by event; see the documentation for the specific +--- event, e.g. `DirChanged` or `TextYankPost`. +--- KEY DESCRIPTION ~ +--- abort Whether the event triggered during +--- an aborting condition (e.g. `c_Esc` or +--- `c_CTRL-C` for `CmdlineLeave`). +--- chan `channel-id` +--- cmdlevel Level of cmdline. +--- cmdtype Type of cmdline, `cmdline-char`. +--- cwd Current working directory. +--- inclusive Motion is `inclusive`, else exclusive. +--- scope Event-specific scope name. +--- operator Current `operator`. Also set for Ex +--- commands (unlike `v:operator`). For +--- example if `TextYankPost` is triggered +--- by the `:yank` Ex command then +--- `v:event.operator` is "y". +--- regcontents Text stored in the register as a +--- `readfile()`-style list of lines. +--- regname Requested register (e.g "x" for "xyy) +--- or the empty string for an unnamed +--- operation. +--- regtype Type of register as returned by +--- `getregtype()`. +--- visual Selection is visual (as opposed to, +--- e.g., via motion). +--- completed_item Current selected complete item on +--- `CompleteChanged`, Is `{}` when no complete +--- item selected. +--- height Height of popup menu on `CompleteChanged` +--- width Width of popup menu on `CompleteChanged` +--- row Row count of popup menu on `CompleteChanged`, +--- relative to screen. +--- col Col count of popup menu on `CompleteChanged`, +--- relative to screen. +--- size Total number of completion items on +--- `CompleteChanged`. +--- scrollbar Is `v:true` if popup menu have scrollbar, or +--- `v:false` if not. +--- changed_window Is `v:true` if the event fired while +--- changing window (or tab) on `DirChanged`. +--- status Job status or exit code, -1 means "unknown". `TermClose` +--- @type any +vim.v.event = ... + +--- The value of the exception most recently caught and not +--- finished. See also `v:throwpoint` and `throw-variables`. +--- Example: +--- +--- ```vim +--- try +--- throw "oops" +--- catch /.*/ +--- echo "caught " .. v:exception +--- endtry +--- ``` +--- +--- Output: "caught oops". +--- @type any +vim.v.exception = ... + +--- Exit code, or `v:null` before invoking the `VimLeavePre` +--- and `VimLeave` autocmds. See `:q`, `:x` and `:cquit`. +--- Example: +--- +--- ```vim +--- :au VimLeave * echo "Exit value is " .. v:exiting +--- ``` +--- @type any +vim.v.exiting = ... + +--- Special value used to put "false" in JSON and msgpack. See +--- `json_encode()`. This value is converted to "v:false" when used +--- as a String (e.g. in `expr5` with string concatenation +--- operator) and to zero when used as a Number (e.g. in `expr5` +--- or `expr7` when used with numeric operators). Read-only. +--- @type any +vim.v['false'] = ... + +--- What should happen after a `FileChangedShell` event was +--- triggered. Can be used in an autocommand to tell Vim what to +--- do with the affected buffer: +--- reload Reload the buffer (does not work if +--- the file was deleted). +--- edit Reload the buffer and detect the +--- values for options such as +--- 'fileformat', 'fileencoding', 'binary' +--- (does not work if the file was +--- deleted). +--- ask Ask the user what to do, as if there +--- was no autocommand. Except that when +--- only the timestamp changed nothing +--- will happen. +--- Nothing, the autocommand should do +--- everything that needs to be done. +--- The default is empty. If another (invalid) value is used then +--- Vim behaves like it is empty, there is no warning message. +--- @type string +vim.v.fcs_choice = ... + +--- The reason why the `FileChangedShell` event was triggered. +--- Can be used in an autocommand to decide what to do and/or what +--- to set v:fcs_choice to. Possible values: +--- deleted file no longer exists +--- conflict file contents, mode or timestamp was +--- changed and buffer is modified +--- changed file contents has changed +--- mode mode of file changed +--- time only file timestamp changed +--- @type string +vim.v.fcs_reason = ... + +--- When evaluating 'includeexpr': the file name that was +--- detected. Empty otherwise. +--- @type string +vim.v.fname = ... + +--- The name of the diff (patch) file. Only valid while +--- evaluating 'patchexpr'. +--- @type string +vim.v.fname_diff = ... + +--- The name of the input file. Valid while evaluating: +--- option used for ~ +--- 'charconvert' file to be converted +--- 'diffexpr' original file +--- 'patchexpr' original file +--- And set to the swap file name for `SwapExists`. +--- @type string +vim.v.fname_in = ... + +--- The name of the new version of the file. Only valid while +--- evaluating 'diffexpr'. +--- @type string +vim.v.fname_new = ... + +--- The name of the output file. Only valid while +--- evaluating: +--- option used for ~ +--- 'charconvert' resulting converted file [1] +--- 'diffexpr' output of diff +--- 'patchexpr' resulting patched file +--- [1] When doing conversion for a write command (e.g., ":w +--- file") it will be equal to v:fname_in. When doing conversion +--- for a read command (e.g., ":e file") it will be a temporary +--- file and different from v:fname_in. +--- @type string +vim.v.fname_out = ... + +--- Used for 'foldtext': dashes representing foldlevel of a closed +--- fold. +--- Read-only in the `sandbox`. `fold-foldtext` +--- @type string +vim.v.folddashes = ... + +--- Used for 'foldtext': last line of closed fold. +--- Read-only in the `sandbox`. `fold-foldtext` +--- @type integer +vim.v.foldend = ... + +--- Used for 'foldtext': foldlevel of closed fold. +--- Read-only in the `sandbox`. `fold-foldtext` +--- @type integer +vim.v.foldlevel = ... + +--- Used for 'foldtext': first line of closed fold. +--- Read-only in the `sandbox`. `fold-foldtext` +--- @type integer +vim.v.foldstart = ... + +--- Variable that indicates whether search highlighting is on. +--- Setting it makes sense only if 'hlsearch' is enabled. Setting +--- this variable to zero acts like the `:nohlsearch` command, +--- setting it to one acts like +--- +--- ```vim +--- let &hlsearch = &hlsearch +--- ``` +--- +--- Note that the value is restored when returning from a +--- function. `function-search-undo`. +--- @type integer +vim.v.hlsearch = ... + +--- Used for the `InsertEnter` and `InsertChange` autocommand +--- events. Values: +--- i Insert mode +--- r Replace mode +--- v Virtual Replace mode +--- @type string +vim.v.insertmode = ... + +--- Key of the current item of a `Dictionary`. Only valid while +--- evaluating the expression used with `map()` and `filter()`. +--- Read-only. +--- @type string +vim.v.key = ... + +--- The current locale setting for messages of the runtime +--- environment. This allows Vim scripts to be aware of the +--- current language. Technical: it's the value of LC_MESSAGES. +--- The value is system dependent. +--- This variable can not be set directly, use the `:language` +--- command. +--- It can be different from `v:ctype` when messages are desired +--- in a different language than what is used for character +--- encoding. See `multi-lang`. +--- @type string +vim.v.lang = ... + +--- The current locale setting for time messages of the runtime +--- environment. This allows Vim scripts to be aware of the +--- current language. Technical: it's the value of LC_TIME. +--- This variable can not be set directly, use the `:language` +--- command. See `multi-lang`. +--- @type string +vim.v.lc_time = ... + +--- Line number for the 'foldexpr' `fold-expr`, 'formatexpr', --- 'indentexpr' and 'statuscolumn' expressions, tab page number --- for 'guitablabel' and 'guitabtooltip'. Only valid while one of ---- these expressions is being evaluated. Read-only when in the |sandbox|. ---- @field lnum integer -vim.v = ... +--- these expressions is being evaluated. Read-only when in the +--- `sandbox`. +--- @type integer +vim.v.lnum = ... + +--- Prefix for calling Lua functions from expressions. +--- See `v:lua-call` for more information. +--- @type any +vim.v.lua = ... + +--- Maximum line length. Depending on where it is used it can be +--- screen columns, characters or bytes. The value currently is +--- 2147483647 on all systems. +--- @type integer +vim.v.maxcol = ... + +--- Column number for a mouse click obtained with `getchar()`. +--- This is the screen column number, like with `virtcol()`. The +--- value is zero when there was no mouse button click. +--- @type integer +vim.v.mouse_col = ... + +--- Line number for a mouse click obtained with `getchar()`. +--- This is the text line number, not the screen line number. The +--- value is zero when there was no mouse button click. +--- @type integer +vim.v.mouse_lnum = ... + +--- Window number for a mouse click obtained with `getchar()`. +--- First window has number 1, like with `winnr()`. The value is +--- zero when there was no mouse button click. +--- @type integer +vim.v.mouse_win = ... + +--- `window-ID` for a mouse click obtained with `getchar()`. +--- The value is zero when there was no mouse button click. +--- @type integer +vim.v.mouse_winid = ... + +--- Dictionary containing msgpack types used by `msgpackparse()` +--- and `msgpackdump()`. All types inside dictionary are fixed +--- (not editable) empty lists. To check whether some list is one +--- of msgpack types, use `is` operator. +--- @type any +vim.v.msgpack_types = ... + +--- Special value used to put "null" in JSON and NIL in msgpack. +--- See `json_encode()`. This value is converted to "v:null" when +--- used as a String (e.g. in `expr5` with string concatenation +--- operator) and to zero when used as a Number (e.g. in `expr5` +--- or `expr7` when used with numeric operators). Read-only. +--- In some places `v:null` can be used for a List, Dict, etc. +--- that is not set. That is slightly different than an empty +--- List, Dict, etc. +--- @type any +vim.v.null = ... + +--- Maximum value of a number. +--- @type integer +vim.v.numbermax = ... + +--- Minimum value of a number (negative). +--- @type integer +vim.v.numbermin = ... + +--- Number of bits in a Number. This is normally 64, but on some +--- systems it may be 32. +--- @type integer +vim.v.numbersize = ... + +--- List of file names that is loaded from the `shada` file on +--- startup. These are the files that Vim remembers marks for. +--- The length of the List is limited by the ' argument of the +--- 'shada' option (default is 100). +--- When the `shada` file is not used the List is empty. +--- Also see `:oldfiles` and `c_#<`. +--- The List can be modified, but this has no effect on what is +--- stored in the `shada` file later. If you use values other +--- than String this will cause trouble. +--- @type string[] +vim.v.oldfiles = ... + +--- The last operator given in Normal mode. This is a single +--- character except for commands starting with or , +--- in which case it is two characters. Best used alongside +--- `v:prevcount` and `v:register`. Useful if you want to cancel +--- Operator-pending mode and then use the operator, e.g.: +--- +--- ```vim +--- :omap O :call MyMotion(v:operator) +--- ``` +--- +--- The value remains set until another operator is entered, thus +--- don't expect it to be empty. +--- v:operator is not set for `:delete`, `:yank` or other Ex +--- commands. +--- Read-only. +--- @type string +vim.v.operator = ... + +--- Command used to set the option. Valid while executing an +--- `OptionSet` autocommand. +--- value option was set via ~ +--- "setlocal" `:setlocal` or `:let l:xxx` +--- "setglobal" `:setglobal` or `:let g:xxx` +--- "set" `:set` or `:let` +--- "modeline" `modeline` +--- @type string +vim.v.option_command = ... + +--- New value of the option. Valid while executing an `OptionSet` +--- autocommand. +--- @type any +vim.v.option_new = ... + +--- Old value of the option. Valid while executing an `OptionSet` +--- autocommand. Depending on the command used for setting and the +--- kind of option this is either the local old value or the +--- global old value. +--- @type any +vim.v.option_old = ... + +--- Old global value of the option. Valid while executing an +--- `OptionSet` autocommand. +--- @type any +vim.v.option_oldglobal = ... + +--- Old local value of the option. Valid while executing an +--- `OptionSet` autocommand. +--- @type any +vim.v.option_oldlocal = ... + +--- Scope of the set command. Valid while executing an +--- `OptionSet` autocommand. Can be either "global" or "local" +--- @type string +vim.v.option_type = ... + +--- The count given for the last but one Normal mode command. +--- This is the v:count value of the previous command. Useful if +--- you want to cancel Visual or Operator-pending mode and then +--- use the count, e.g.: +--- +--- ```vim +--- :vmap % :call MyFilter(v:prevcount) +--- ``` +--- +--- Read-only. +--- @type integer +vim.v.prevcount = ... + +--- Normally zero. Set to one after using ":profile start". +--- See `profiling`. +--- @type integer +vim.v.profiling = ... + +--- The name by which Nvim was invoked (with path removed). +--- Read-only. +--- @type string +vim.v.progname = ... + +--- Absolute path to the current running Nvim. +--- Read-only. +--- @type string +vim.v.progpath = ... + +--- The name of the register in effect for the current normal mode +--- command (regardless of whether that command actually used a +--- register). Or for the currently executing normal mode mapping +--- (use this in custom commands that take a register). +--- If none is supplied it is the default register '"', unless +--- 'clipboard' contains "unnamed" or "unnamedplus", then it is +--- "*" or '+'. +--- Also see `getreg()` and `setreg()` +--- @type string +vim.v.register = ... + +--- Relative line number for the 'statuscolumn' expression. +--- Read-only. +--- @type integer +vim.v.relnum = ... + +--- String describing the script or function that caused the +--- screen to scroll up. It's only set when it is empty, thus the +--- first reason is remembered. It is set to "Unknown" for a +--- typed command. +--- This can be used to find out why your script causes the +--- hit-enter prompt. +--- @type any +vim.v.scrollstart = ... + +--- Search direction: 1 after a forward search, 0 after a +--- backward search. It is reset to forward when directly setting +--- the last search pattern, see `quote/`. +--- Note that the value is restored when returning from a +--- function. `function-search-undo`. +--- Read-write. +--- @type integer +vim.v.searchforward = ... + +--- Primary listen-address of Nvim, the first item returned by +--- `serverlist()`. Usually this is the named pipe created by Nvim +--- at `startup` or given by `--listen` (or the deprecated +--- `$NVIM_LISTEN_ADDRESS` env var). +--- +--- See also `serverstart()` `serverstop()`. +--- Read-only. +--- +--- *$NVIM* +--- $NVIM is set by `terminal` and `jobstart()`, and is thus +--- a hint that the current environment is a subprocess of Nvim. +--- Example: +--- +--- ```vim +--- if $NVIM +--- echo nvim_get_chan_info(v:parent) +--- endif +--- ``` +--- +--- Note the contents of $NVIM may change in the future. +--- @type string +vim.v.servername = ... + +--- Result of the last shell command. When non-zero, the last +--- shell command had an error. When zero, there was no problem. +--- This only works when the shell returns the error code to Vim. +--- The value -1 is often used when the command could not be +--- executed. Read-only. +--- Example: +--- +--- ```vim +--- !mv foo bar +--- if v:shell_error +--- echo 'could not rename "foo" to "bar"!' +--- endif +--- ``` +--- @type string +vim.v.shell_error = ... + +--- Last given status message. +--- Modifiable (can be set). +--- @type string +vim.v.statusmsg = ... + +--- `channel-id` corresponding to stderr. The value is always 2; +--- use this variable to make your code more descriptive. +--- Unlike stdin and stdout (see `stdioopen()`), stderr is always +--- open for writing. Example: +--- +--- ```vim +--- :call chansend(v:stderr, "error: toaster empty\n") +--- ``` +--- @type string +vim.v.stderr = ... + +--- `SwapExists` autocommands can set this to the selected choice +--- for handling an existing swapfile: +--- 'o' Open read-only +--- 'e' Edit anyway +--- 'r' Recover +--- 'd' Delete swapfile +--- 'q' Quit +--- 'a' Abort +--- The value should be a single-character string. An empty value +--- results in the user being asked, as would happen when there is +--- no SwapExists autocommand. The default is empty. +--- @type string +vim.v.swapchoice = ... + +--- Normal mode command to be executed after a file has been +--- opened. Can be used for a `SwapExists` autocommand to have +--- another Vim open the file and jump to the right place. For +--- example, when jumping to a tag the value is ":tag tagname\r". +--- For ":edit +cmd file" the value is ":cmd\r". +--- @type string +vim.v.swapcommand = ... + +--- Name of the swapfile found. +--- Only valid during `SwapExists` event. +--- Read-only. +--- @type string +vim.v.swapname = ... + +--- Value of `Blob` type. Read-only. See: `type()` +--- @type integer +vim.v.t_blob = ... + +--- Value of `Boolean` type. Read-only. See: `type()` +--- @type integer +vim.v.t_bool = ... + +--- Value of `Dictionary` type. Read-only. See: `type()` +--- @type integer +vim.v.t_dict = ... + +--- Value of `Float` type. Read-only. See: `type()` +--- @type integer +vim.v.t_float = ... + +--- Value of `Funcref` type. Read-only. See: `type()` +--- @type integer +vim.v.t_func = ... + +--- Value of `List` type. Read-only. See: `type()` +--- @type integer +vim.v.t_list = ... + +--- Value of `Number` type. Read-only. See: `type()` +--- @type integer +vim.v.t_number = ... + +--- Value of `String` type. Read-only. See: `type()` +--- @type integer +vim.v.t_string = ... + +--- The value of the most recent OSC or DCS escape sequence +--- received by Nvim from the terminal. This can be read in a +--- `TermResponse` event handler after querying the terminal using +--- another escape sequence. +--- @type any +vim.v.termresponse = ... + +--- Must be set before using `test_garbagecollect_now()`. +--- @type any +vim.v.testing = ... + +--- Full filename of the last loaded or saved session file. +--- Empty when no session file has been saved. See `:mksession`. +--- Modifiable (can be set). +--- @type any +vim.v.this_session = ... + +--- The point where the exception most recently caught and not +--- finished was thrown. Not set when commands are typed. See +--- also `v:exception` and `throw-variables`. +--- Example: +--- +--- ```vim +--- try +--- throw "oops" +--- catch /.*/ +--- echo "Exception from" v:throwpoint +--- endtry +--- ``` +--- +--- Output: "Exception from test.vim, line 2" +--- @type any +vim.v.throwpoint = ... + +--- Special value used to put "true" in JSON and msgpack. See +--- `json_encode()`. This value is converted to "v:true" when used +--- as a String (e.g. in `expr5` with string concatenation +--- operator) and to one when used as a Number (e.g. in `expr5` or +--- `expr7` when used with numeric operators). Read-only. +--- @type any +vim.v['true'] = ... + +--- Value of the current item of a `List` or `Dictionary`. Only +--- valid while evaluating the expression used with `map()` and +--- `filter()`. Read-only. +--- @type any +vim.v.val = ... + +--- Vim version number: major version times 100 plus minor +--- version. Vim 5.0 is 500, Vim 5.1 is 501. +--- Read-only. +--- Use `has()` to check the Nvim (not Vim) version: +--- +--- ```vim +--- :if has("nvim-0.2.1") +--- ``` +--- @type integer +vim.v.version = ... + +--- 0 during startup, 1 just before `VimEnter`. +--- Read-only. +--- @type integer +vim.v.vim_did_enter = ... + +--- Virtual line number for the 'statuscolumn' expression. +--- Negative when drawing the status column for virtual lines, zero +--- when drawing an actual buffer line, and positive when drawing +--- the wrapped part of a buffer line. +--- Read-only. +--- @type integer +vim.v.virtnum = ... + +--- Last given warning message. +--- Modifiable (can be set). +--- @type string +vim.v.warningmsg = ... + +--- Application-specific window "handle" which may be set by any +--- attached UI. Defaults to zero. +--- Note: For Nvim `windows` use `winnr()` or `win_getid()`, see +--- `window-ID`. +--- @type integer +vim.v.windowid = ... -- cgit From 6700127b30d55e6ddf70495e7b886464172d7ac6 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 22 Dec 2023 10:33:34 +0800 Subject: vim-patch:9.0.2183: Maximum callback depth is not configurable (#26703) Problem: Maximum callback depth is not configurable. Solution: Revert patch 9.0.2103. Set 'maxfuncdepth' in test. fixes: vim/vim#13732 closes: vim/vim#13736 https://github.com/vim/vim/commit/fe583b1e5987fbfdb5f2141c133dbff9665ed301 --- runtime/lua/vim/_meta/options.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 6b7cfa79b3..38ab66c96d 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -4037,6 +4037,7 @@ vim.go.mat = vim.go.matchtime --- Increasing this limit above 200 also changes the maximum for Ex --- command recursion, see `E169`. --- See also `:function`. +--- Also used for maximum depth of callback functions. --- --- @type integer vim.o.maxfuncdepth = 100 -- cgit From 19aba5916a4064b503894185072fb1c47a41e023 Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Fri, 22 Dec 2023 10:55:39 +0100 Subject: docs(options): add codeblock annotations to options.lua (#26696) Also consistently remove leading colons in examples Co-authored-by: zeertzjq --- runtime/lua/vim/_meta/options.lua | 652 ++++++++++++++++++++++---------------- 1 file changed, 385 insertions(+), 267 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 38ab66c96d..209c27cfd8 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -137,8 +137,9 @@ vim.bo.ai = vim.bo.autoindent --- `timestamp` --- If this option has a local value, use this command to switch back to --- using the global value: ---- ``` ---- :set autoread< +--- +--- ```vim +--- set autoread< --- ``` --- --- @@ -198,10 +199,11 @@ vim.go.awa = vim.go.autowriteall --- --- Normally this option would be set in the vimrc file. Possibly --- depending on the terminal name. Example: ---- ``` ---- :if $TERM ==# "xterm" ---- : set background=dark ---- :endif +--- +--- ```vim +--- if $TERM ==# "xterm" +--- set background=dark +--- endif --- ``` --- When this option is changed, the default settings for the highlight groups --- will change. To use other settings, place ":highlight" commands AFTER @@ -348,14 +350,16 @@ vim.go.bkc = vim.go.backupcopy --- - Environment variables are expanded `:set_env`. --- - Careful with '\' characters, type one before a space, type two to --- get one in the option (see `option-backslash`), for example: ---- ``` ---- :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces +--- +--- ```vim +--- set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces --- ``` --- --- See also 'backup' and 'writebackup' options. --- If you want to hide your backup files on Unix, consider this value: ---- ``` ---- :set backupdir=./.backup,~/.backup,.,/tmp +--- +--- ```vim +--- set backupdir=./.backup,~/.backup,.,/tmp --- ``` --- You must create a ".backup" directory in each directory and in your --- home directory for this to work properly. @@ -381,8 +385,9 @@ vim.go.bdir = vim.go.backupdir --- If you like to keep a lot of backups, you could use a BufWritePre --- autocommand to change 'backupext' just before writing the file to --- include a timestamp. ---- ``` ---- :au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~' +--- +--- ```vim +--- au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~' --- ``` --- Use 'backupdir' to put the backup in a different directory. --- @@ -409,7 +414,7 @@ vim.go.bex = vim.go.backupext --- $HOME you must expand it explicitly, e.g.: --- --- ```vim ---- :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' +--- let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' --- ``` --- Note that the default also makes sure that "crontab -e" works (when a --- backup would be made by renaming the original file crontab won't see @@ -710,8 +715,9 @@ vim.go.cdh = vim.go.cdhome --- If the default value taken from $CDPATH is not what you want, include --- a modified version of the following command in your vimrc file to --- override it: ---- ``` ---- :let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g') +--- +--- ```vim +--- let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g') --- ``` --- This option cannot be set from a `modeline` or in the `sandbox`, for --- security reasons. @@ -727,9 +733,10 @@ vim.go.cd = vim.go.cdpath --- Only non-printable keys are allowed. --- The key can be specified as a single character, but it is difficult to --- type. The preferred way is to use the <> notation. Examples: ---- ``` ---- :exe "set cedit=\\" ---- :exe "set cedit=\\" +--- +--- ```vim +--- exe "set cedit=\\" +--- exe "set cedit=\\" --- ``` --- `Nvi` also has this option, but it only uses the first character. --- See `cmdwin`. @@ -763,7 +770,8 @@ vim.bo.channel = vim.o.channel --- is done internally by Vim, 'charconvert' is not used for this. --- Also used for Unicode conversion. --- Example: ---- ``` +--- +--- ```vim --- set charconvert=CharConvert() --- fun CharConvert() --- system("recode " @@ -829,7 +837,8 @@ vim.bo.cino = vim.bo.cinoptions --- Keywords that are interpreted as a C++ scope declaration by `cino-g`. --- Useful e.g. for working with the Qt framework that defines additional --- scope declarations "signals", "public slots" and "private slots": ---- ``` +--- +--- ```vim --- set cinscopedecls+=signals,public\ slots,private\ slots --- ``` --- @@ -916,10 +925,12 @@ vim.go.cwh = vim.go.cmdwinheight --- text. Will make screen redrawing slower. --- The screen column can be an absolute number, or a number preceded with --- '+' or '-', which is added to or subtracted from 'textwidth'. ---- ``` ---- :set cc=+1 " highlight column after 'textwidth' ---- :set cc=+1,+2,+3 " highlight three columns after 'textwidth' ---- :hi ColorColumn ctermbg=lightgrey guibg=lightgrey +--- +--- ```vim +--- +--- set cc=+1 " highlight column after 'textwidth' +--- set cc=+1,+2,+3 " highlight three columns after 'textwidth' +--- hi ColorColumn ctermbg=lightgrey guibg=lightgrey --- ``` --- --- When 'textwidth' is zero then the items with '-' and '+' are not used. @@ -941,8 +952,9 @@ vim.wo.cc = vim.wo.colorcolumn --- the GUI it is always possible and Vim limits the number of columns to --- what fits on the screen. You can use this command to get the widest --- window possible: ---- ``` ---- :set columns=9999 +--- +--- ```vim +--- set columns=9999 --- ``` --- Minimum value is 12, maximum value is 10000. --- @@ -985,8 +997,9 @@ vim.bo.cms = vim.bo.commentstring --- kspell use the currently active spell checking `spell` --- k{dict} scan the file {dict}. Several "k" flags can be given, --- patterns are valid too. For example: ---- ``` ---- :set cpt=k/usr/dict/*,k~/spanish +--- +--- ```vim +--- set cpt=k/usr/dict/*,k~/spanish --- ``` --- s scan the files given with the 'thesaurus' option --- s{tsr} scan the file {tsr}. Several "s" flags can be given, patterns @@ -1419,7 +1432,8 @@ vim.wo.crb = vim.wo.cursorbind --- slower. --- If you only want the highlighting in the current window you can use --- these autocommands: ---- ``` +--- +--- ```vim --- au WinLeave * set nocursorline nocursorcolumn --- au WinEnter * set cursorline cursorcolumn --- ``` @@ -1502,7 +1516,8 @@ vim.go.debug = vim.o.debug --- ``` --- When using the ":set" command, you need to double the backslashes! --- To avoid that use `:let` with a single quote string: ---- ``` +--- +--- ```vim --- let &l:define = '^\s*\ze\k\+\s*=\s*function(' --- ``` --- @@ -1681,11 +1696,12 @@ vim.go.dex = vim.go.diffexpr --- histogram histogram diff algorithm --- --- Examples: ---- ``` ---- :set diffopt=internal,filler,context:4 ---- :set diffopt= ---- :set diffopt=internal,filler,foldcolumn:3 ---- :set diffopt-=internal " do NOT use the internal diff parser +--- +--- ```vim +--- set diffopt=internal,filler,context:4 +--- set diffopt= +--- set diffopt=internal,filler,foldcolumn:3 +--- set diffopt-=internal " do NOT use the internal diff parser --- ``` --- --- @@ -1736,8 +1752,9 @@ vim.go.dg = vim.go.digraph --- - Environment variables are expanded `:set_env`. --- - Careful with '\' characters, type one before a space, type two to --- get one in the option (see `option-backslash`), for example: ---- ``` ---- :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces +--- +--- ```vim +--- set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces --- ``` --- --- Editing the same file twice will result in a warning. Using "/tmp" on @@ -1924,8 +1941,9 @@ vim.go.efm = vim.go.errorformat --- When set to "all" or when "all" is one of the items, all autocommand --- events are ignored, autocommands will not be executed. --- Otherwise this is a comma-separated list of event names. Example: ---- ``` ---- :set ei=WinEnter,WinLeave +--- +--- ```vim +--- set ei=WinEnter,WinLeave --- ``` --- --- @@ -2021,7 +2039,8 @@ vim.bo.fenc = vim.bo.fileencoding --- "ucs-bom", which requires the BOM to be present). If you prefer --- another encoding use an BufReadPost autocommand event to test if your --- preferred encoding is to be used. Example: ---- ``` +--- +--- ```vim --- au BufReadPost * if search('\S', 'w') == 0 | --- \ set fenc=iso-2022-jp | endif --- ``` @@ -2031,8 +2050,9 @@ vim.bo.fenc = vim.bo.fileencoding --- not used. --- Note that 'fileencodings' is not used for a new file, the global value --- of 'fileencoding' is used instead. You can set it with: ---- ``` ---- :setglobal fenc=iso-8859-2 +--- +--- ```vim +--- setglobal fenc=iso-8859-2 --- ``` --- This means that a non-existing file may get a different encoding than --- an empty file. @@ -2156,14 +2176,12 @@ vim.go.fic = vim.go.fileignorecase --- this use the ":filetype on" command. `:filetype` --- Setting this option to a different value is most useful in a modeline, --- for a file for which the file type is not automatically recognized. ---- Example, for in an IDL file: ---- ``` +--- Example, for in an IDL file: >c --- /* vim: set filetype=idl : */ --- ``` --- `FileType` `filetypes` --- When a dot appears in the value then this separates two filetype ---- names. Example: ---- ``` +--- names. Example: >c --- /* vim: set filetype=c.doxygen : */ --- ``` --- This will use the "c" filetype first, then the "doxygen" filetype. @@ -2216,8 +2234,9 @@ vim.bo.ft = vim.bo.filetype --- default to single-byte alternatives. --- --- Example: ---- ``` ---- :set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:- +--- +--- ```vim +--- set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:- --- ``` --- --- For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items @@ -2475,8 +2494,9 @@ vim.wo.fdt = vim.wo.foldtext --- it yet! --- --- Example: ---- ``` ---- :set formatexpr=mylang#Format() +--- +--- ```vim +--- set formatexpr=mylang#Format() --- ``` --- This will invoke the mylang#Format() function in the --- autoload/mylang.vim file in 'runtimepath'. `autoload` @@ -2492,7 +2512,8 @@ vim.wo.fdt = vim.wo.foldtext --- --- If the expression starts with s: or ``, then it is replaced with --- the script ID (`local-function`). Example: ---- ``` +--- +--- ```vim --- set formatexpr=s:MyFormatExpr() --- set formatexpr=SomeFormatExpr() --- ``` @@ -2618,8 +2639,9 @@ vim.go.gfm = vim.go.grepformat --- `option-backslash` about including spaces and backslashes. --- When your "grep" accepts the "-H" argument, use this to make ":grep" --- also work well with a single file: ---- ``` ---- :set grepprg=grep\ -nH +--- +--- ```vim +--- set grepprg=grep\ -nH --- ``` --- Special value: When 'grepprg' is set to "internal" the `:grep` command --- works like `:vimgrep`, `:lgrep` like `:lvimgrep`, `:grepadd` like @@ -2641,12 +2663,14 @@ vim.go.gp = vim.go.grepprg --- terminals. See `tui-cursor-shape`. --- --- To disable cursor-styling, reset the option: ---- ``` ---- :set guicursor= +--- +--- ```vim +--- set guicursor= --- ``` --- To enable mode shapes, "Cursor" highlight, and blinking: ---- ``` ---- :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 +--- +--- ```vim +--- set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 --- \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor --- \,sm:block-blinkwait175-blinkoff150-blinkon175 --- ``` @@ -2680,8 +2704,9 @@ vim.go.gp = vim.go.grepprg --- the cursor is shown and blinkoff is the time that the --- cursor is not shown. Times are in msec. When one of --- the numbers is zero, there is no blinking. E.g.: ---- ``` ---- :set guicursor=n:blinkon0 +--- +--- ```vim +--- set guicursor=n:blinkon0 --- ``` --- - Default is "blinkon0" for each mode. --- {group-name} @@ -2721,9 +2746,10 @@ vim.go.gp = vim.go.grepprg --- blinking: "a:blinkon0" --- --- Examples of cursor highlighting: ---- ``` ---- :highlight Cursor gui=reverse guifg=NONE guibg=NONE ---- :highlight Cursor gui=NONE guifg=bg guibg=fg +--- +--- ```vim +--- highlight Cursor gui=reverse guifg=NONE guibg=NONE +--- highlight Cursor gui=NONE guifg=bg guibg=fg --- ``` --- --- @@ -2743,8 +2769,9 @@ vim.go.gcr = vim.go.guicursor --- precede it with a backslash. Setting an option requires an extra --- backslash before a space and a backslash. See also --- `option-backslash`. For example: ---- ``` ---- :set guifont=Screen15,\ 7x13,font\\,with\\,commas +--- +--- ```vim +--- set guifont=Screen15,\ 7x13,font\\,with\\,commas --- ``` --- will make Vim try to use the font "Screen15" first, and if it fails it --- will try to use "7x13" and then "font,with,commas" instead. @@ -2757,16 +2784,18 @@ vim.go.gcr = vim.go.guicursor --- will try to find the related bold and italic fonts. --- --- For Win32 and Mac OS: ---- ``` ---- :set guifont=* +--- +--- ```vim +--- set guifont=* --- ``` --- will bring up a font requester, where you can pick the font you want. --- --- The font name depends on the GUI used. --- --- For Mac OSX you can use something like this: ---- ``` ---- :set guifont=Monaco:h10 +--- +--- ```vim +--- set guifont=Monaco:h10 --- ``` --- *E236* --- Note that the fonts must be mono-spaced (all characters have the same @@ -2793,9 +2822,10 @@ vim.go.gcr = vim.go.guicursor --- - A '_' can be used in the place of a space, so you don't need to use --- backslashes to escape the spaces. --- - Examples: ---- ``` ---- :set guifont=courier_new:h12:w5:b:cRUSSIAN ---- :set guifont=Andale_Mono:h7.5:w4.5 +--- +--- ```vim +--- set guifont=courier_new:h12:w5:b:cRUSSIAN +--- set guifont=Andale_Mono:h7.5:w4.5 --- ``` --- --- @@ -2949,8 +2979,9 @@ vim.go.gtl = vim.go.guitablabel --- pages line. When empty Vim will use a default tooltip. --- This option is otherwise just like 'guitablabel' above. --- You can include a line break. Simplest method is to use `:let`: ---- ``` ---- :let &guitabtooltip = "line one\nline two" +--- +--- ```vim +--- let &guitabtooltip = "line one\nline two" --- ``` --- --- @@ -2994,8 +3025,9 @@ vim.go.hh = vim.go.helpheight --- another language, but that will only find tags that exist in that --- language and not in the English help. --- Example: ---- ``` ---- :set helplang=de,it +--- +--- ```vim +--- set helplang=de,it --- ``` --- This will first search German, then Italian and finally English help --- files. @@ -3131,8 +3163,9 @@ vim.go.imd = vim.go.imdisable --- 2 :lmap is off and IM is ON --- To always reset the option to zero when leaving Insert mode with --- this can be used: ---- ``` ---- :inoremap :set iminsert=0 +--- +--- ```vim +--- inoremap :set iminsert=0 --- ``` --- This makes :lmap and IM turn off automatically when leaving Insert --- mode. @@ -3206,15 +3239,17 @@ vim.go.inc = vim.go.include --- Expression to be used to transform the string found with the 'include' --- option to a file name. Mostly useful to change "." to "/" for Java: ---- ``` ---- :setlocal includeexpr=substitute(v:fname,'\\.','/','g') +--- +--- ```vim +--- setlocal includeexpr=substitute(v:fname,'\\.','/','g') --- ``` --- The "v:fname" variable will be set to the file name that was detected. --- Note the double backslash: the `:set` command first halves them, then --- one remains in the value, where "\." matches a dot literally. For --- simple character replacements `tr()` avoids the need for escaping: ---- ``` ---- :setlocal includeexpr=tr(v:fname,'.','/') +--- +--- ```vim +--- setlocal includeexpr=tr(v:fname,'.','/') --- ``` --- --- Also used for the `gf` command if an unmodified file name can't be @@ -3223,7 +3258,8 @@ vim.go.inc = vim.go.include --- --- If the expression starts with s: or ``, then it is replaced with --- the script ID (`local-function`). Example: ---- ``` +--- +--- ```vim --- setlocal includeexpr=s:MyIncludeExpr(v:fname) --- setlocal includeexpr=SomeIncludeExpr(v:fname) --- ``` @@ -3262,7 +3298,8 @@ vim.bo.inex = vim.bo.includeexpr --- If you don't want to turn 'hlsearch' on, but want to highlight all --- matches while searching, you can turn on and off 'hlsearch' with --- autocmd. Example: ---- ``` +--- +--- ```vim --- augroup vimrc-incsearch-highlight --- autocmd! --- autocmd CmdlineEnter /,\? :set hlsearch @@ -3295,7 +3332,8 @@ vim.go.is = vim.go.incsearch --- --- If the expression starts with s: or ``, then it is replaced with --- the script ID (`local-function`). Example: ---- ``` +--- +--- ```vim --- set indentexpr=s:MyIndentExpr() --- set indentexpr=SomeIndentExpr() --- ``` @@ -3311,8 +3349,9 @@ vim.go.is = vim.go.incsearch --- not change the text, jump to another window, etc. Afterwards the --- cursor position is always restored, thus the cursor may be moved. --- Normally this option would be set to call a function: ---- ``` ---- :set indentexpr=GetMyIndent() +--- +--- ```vim +--- set indentexpr=GetMyIndent() --- ``` --- Error messages will be suppressed, unless the 'debug' option contains --- "msg". @@ -3540,9 +3579,10 @@ vim.go.km = vim.go.keymodel --- a [count] for the "K" command to a section number. --- See `option-backslash` about including spaces and backslashes. --- Example: ---- ``` ---- :set keywordprg=man\ -s ---- :set keywordprg=:Man +--- +--- ```vim +--- set keywordprg=man\ -s +--- set keywordprg=:Man --- ``` --- This option cannot be set from a `modeline` or in the `sandbox`, for --- security reasons. @@ -3569,12 +3609,14 @@ vim.go.kp = vim.go.keywordprg --- security reasons. --- --- Example (for Greek, in UTF-8): *greek* ---- ``` ---- :set langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz +--- +--- ```vim +--- set langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz --- ``` --- Example (exchanges meaning of z and y for commands): ---- ``` ---- :set langmap=zy,yz,ZY,YZ +--- +--- ```vim +--- set langmap=zy,yz,ZY,YZ --- ``` --- --- The 'langmap' option is a list of parts, separated with commas. Each @@ -3607,28 +3649,32 @@ vim.go.lmap = vim.go.langmap --- Language to use for menu translation. Tells which file is loaded --- from the "lang" directory in 'runtimepath': ---- ``` +--- +--- ```vim --- "lang/menu_" .. &langmenu .. ".vim" --- ``` --- (without the spaces). For example, to always use the Dutch menus, no --- matter what $LANG is set to: ---- ``` ---- :set langmenu=nl_NL.ISO_8859-1 +--- +--- ```vim +--- set langmenu=nl_NL.ISO_8859-1 --- ``` --- When 'langmenu' is empty, `v:lang` is used. --- Only normal file name characters can be used, `/\*?[|<>` are illegal. --- If your $LANG is set to a non-English language but you do want to use --- the English menus: ---- ``` ---- :set langmenu=none +--- +--- ```vim +--- set langmenu=none --- ``` --- This option must be set before loading menus, switching on filetype --- detection or syntax highlighting. Once the menus are defined setting --- this option has no effect. But you could do this: ---- ``` ---- :source $VIMRUNTIME/delmenu.vim ---- :set langmenu=de_DE.ISO_8859-1 ---- :source $VIMRUNTIME/menu.vim +--- +--- ```vim +--- source $VIMRUNTIME/delmenu.vim +--- set langmenu=de_DE.ISO_8859-1 +--- source $VIMRUNTIME/menu.vim --- ``` --- Warning: This deletes all menus that you defined yourself! --- @@ -3701,8 +3747,9 @@ vim.wo.lbr = vim.wo.linebreak --- to use the size for the GUI, put the command in your `gvimrc` file. --- Vim limits the number of lines to what fits on the screen. You can --- use this command to get the tallest window possible: ---- ``` ---- :set lines=999 +--- +--- ```vim +--- set lines=999 --- ``` --- Minimum value is 2, maximum value is 1000. --- @@ -3771,8 +3818,9 @@ vim.go.lw = vim.go.lispwords --- The cursor is displayed at the start of the space a Tab character --- occupies, not at the end as usual in Normal mode. To get this cursor --- position while displaying Tabs with spaces, use: ---- ``` ---- :set list lcs=tab:\ \ +--- +--- ```vim +--- set list lcs=tab:\ \ --- ``` --- --- Note that list mode will also affect formatting (set with 'textwidth' @@ -3837,8 +3885,9 @@ vim.wo.list = vim.o.list --- leading spaces are blank. Overrides the "space" and --- "multispace" settings for leading spaces. You can --- combine it with "tab:", for example: ---- ``` ---- :set listchars+=tab:>-,lead:. +--- +--- ```vim +--- set listchars+=tab:>-,lead:. --- ``` --- --- *lcs-leadmultispace* @@ -3878,7 +3927,8 @@ vim.wo.list = vim.o.list --- be used. All characters must be single width. --- --- Each character can be specified as hex: ---- ``` +--- +--- ```vim --- set listchars=eol:\\x24 --- set listchars=eol:\\u21b5 --- set listchars=eol:\\U000021b5 @@ -3887,10 +3937,11 @@ vim.wo.list = vim.o.list --- must be exactly 2 for \\x, 4 for \\u and 8 for \\U. --- --- Examples: ---- ``` ---- :set lcs=tab:>-,trail:- ---- :set lcs=tab:>-,eol:<,nbsp:% ---- :set lcs=extends:>,precedes:< +--- +--- ```vim +--- set lcs=tab:>-,trail:- +--- set lcs=tab:>-,eol:<,nbsp:% +--- set lcs=extends:>,precedes:< --- ``` --- `hl-NonText` highlighting will be used for "eol", "extends" and --- "precedes". `hl-Whitespace` for "nbsp", "space", "tab", "multispace", @@ -3955,8 +4006,9 @@ vim.go.mef = vim.go.makeef --- This would be mostly useful when you use MS-Windows. If iconv is --- enabled, setting 'makeencoding' to "char" has the same effect as --- setting to the system locale encoding. Example: ---- ``` ---- :set makeencoding=char " system locale is used +--- +--- ```vim +--- set makeencoding=char " system locale is used --- ``` --- --- @@ -3977,13 +4029,15 @@ vim.go.menc = vim.go.makeencoding --- Note that a '|' must be escaped twice: once for ":set" and once for --- the interpretation of a command. When you use a filter called --- "myfilter" do it like this: ---- ``` ---- :set makeprg=gmake\ \\\|\ myfilter +--- +--- ```vim +--- set makeprg=gmake\ \\\|\ myfilter --- ``` --- The placeholder "$*" can be given (even multiple times) to specify --- where the arguments will be included, for example: ---- ``` ---- :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} +--- +--- ```vim +--- set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} --- ``` --- This option cannot be set from a `modeline` or in the `sandbox`, for --- security reasons. @@ -4003,13 +4057,15 @@ vim.go.mp = vim.go.makeprg --- The characters must be separated by a colon. --- The pairs must be separated by a comma. Example for including '<' and --- '>' (for HTML): ---- ``` ---- :set mps+=<:> +--- +--- ```vim +--- set mps+=<:> --- ``` --- A more exotic example, to jump between the '=' and ';' in an --- assignment, useful for languages like C and Java: ---- ``` ---- :au FileType c,cpp,java set mps+==:; +--- +--- ```vim +--- au FileType c,cpp,java set mps+==:; --- ``` --- For a more advanced way of using "%", see the matchit.vim plugin in --- the $VIMRUNTIME/plugin directory. `add-local-help` @@ -4117,8 +4173,9 @@ vim.go.mis = vim.go.menuitems --- The languages for which these numbers are important are Italian and --- Hungarian. The default works for when you have about 512 Mbyte. If --- you have 1 Gbyte you could use: ---- ``` ---- :set mkspellmem=900000,3000,800 +--- +--- ```vim +--- set mkspellmem=900000,3000,800 --- ``` --- If you have less than 512 Mbyte `:mkspell` may fail for some --- languages, no matter what you set 'mkspellmem' to. @@ -4213,8 +4270,9 @@ vim.go.more = vim.o.more --- Enables mouse support. For example, to enable the mouse in Normal mode --- and Visual mode: ---- ``` ---- :set mouse=nv +--- +--- ```vim +--- set mouse=nv --- ``` --- --- To temporarily disable mouse support, hold the shift key while using @@ -4306,19 +4364,20 @@ vim.go.mh = vim.go.mousehide --- See `mouse-overview`. But mappings are NOT used for modeless selection. --- --- Example: ---- ``` ---- :map ---- :map ---- :map ---- :map <2-S-LeftMouse> <2-RightMouse> ---- :map <2-S-LeftDrag> <2-RightDrag> ---- :map <2-S-LeftRelease> <2-RightRelease> ---- :map <3-S-LeftMouse> <3-RightMouse> ---- :map <3-S-LeftDrag> <3-RightDrag> ---- :map <3-S-LeftRelease> <3-RightRelease> ---- :map <4-S-LeftMouse> <4-RightMouse> ---- :map <4-S-LeftDrag> <4-RightDrag> ---- :map <4-S-LeftRelease> <4-RightRelease> +--- +--- ```vim +--- map +--- map +--- map +--- map <2-S-LeftMouse> <2-RightMouse> +--- map <2-S-LeftDrag> <2-RightDrag> +--- map <2-S-LeftRelease> <2-RightRelease> +--- map <3-S-LeftMouse> <3-RightMouse> +--- map <3-S-LeftDrag> <3-RightDrag> +--- map <3-S-LeftRelease> <3-RightRelease> +--- map <4-S-LeftMouse> <4-RightMouse> +--- map <4-S-LeftDrag> <4-RightDrag> +--- map <4-S-LeftRelease> <4-RightRelease> --- ``` --- --- Mouse commands requiring the CTRL modifier can be simulated by typing @@ -4358,8 +4417,9 @@ vim.go.mousemev = vim.go.mousemoveevent --- a count of 0. --- --- Example: ---- ``` ---- :set mousescroll=ver:5,hor:2 +--- +--- ```vim +--- set mousescroll=ver:5,hor:2 --- ``` --- Will make Nvim scroll 5 lines at a time when scrolling vertically, and --- scroll 2 columns at a time when scrolling horizontally. @@ -4422,8 +4482,9 @@ vim.go.mousescroll = vim.o.mousescroll --- pointer. --- --- Example: ---- ``` ---- :set mouseshape=s:udsizing,m:no +--- +--- ```vim +--- set mouseshape=s:udsizing,m:no --- ``` --- will make the mouse turn to a sizing arrow over the status lines and --- indicate no input when the hit-enter prompt is displayed (since @@ -4627,28 +4688,33 @@ vim.go.pm = vim.go.patchmode --- starting with "/", "./" or "../"). The directories in the 'path' --- option may be relative or absolute. --- - Use commas to separate directory names: ---- ``` ---- :set path=.,/usr/local/include,/usr/include +--- +--- ```vim +--- set path=.,/usr/local/include,/usr/include --- ``` --- - Spaces can also be used to separate directory names. To have a --- space in a directory name, precede it with an extra backslash, and --- escape the space: ---- ``` ---- :set path=.,/dir/with\\\ space +--- +--- ```vim +--- set path=.,/dir/with\\\ space --- ``` --- - To include a comma in a directory name precede it with an extra --- backslash: ---- ``` ---- :set path=.,/dir/with\\,comma +--- +--- ```vim +--- set path=.,/dir/with\\,comma --- ``` --- - To search relative to the directory of the current file, use: ---- ``` ---- :set path=. +--- +--- ```vim +--- set path=. --- ``` --- - To search in the current directory use an empty string between two --- commas: ---- ``` ---- :set path=,, +--- +--- ```vim +--- set path=,, --- ``` --- - A directory name may end in a ':' or '/'. --- - Environment variables are expanded `:set_env`. @@ -4657,12 +4723,14 @@ vim.go.pm = vim.go.patchmode --- - Search upwards and downwards in a directory tree using "*", "**" and --- ";". See `file-searching` for info and syntax. --- - Careful with '\' characters, type two to get one in the option: ---- ``` ---- :set path=.,c:\\include +--- +--- ```vim +--- set path=.,c:\\include --- ``` --- Or just use '/' instead: ---- ``` ---- :set path=.,c:/include +--- +--- ```vim +--- set path=.,c:/include --- ``` --- Don't forget "." or files won't even be found in the same directory as --- the file! @@ -4673,18 +4741,21 @@ vim.go.pm = vim.go.patchmode --- The use of `:set+=` and `:set-=` is preferred when adding or removing --- directories from the list. This avoids problems when a future version --- uses another default. To remove the current directory use: ---- ``` ---- :set path-= +--- +--- ```vim +--- set path-= --- ``` --- To add the current directory use: ---- ``` ---- :set path+= +--- +--- ```vim +--- set path+= --- ``` --- To use an environment variable, you probably need to replace the --- separator. Here is an example to append $INCL, in which directory --- names are separated with a semi-colon: ---- ``` ---- :let &path = &path .. "," .. substitute($INCL, ';', ',', 'g') +--- +--- ```vim +--- let &path = &path .. "," .. substitute($INCL, ';', ',', 'g') --- ``` --- Replace the ';' with a ':' or whatever separator is used. Note that --- this doesn't work when $INCL contains a comma or white space. @@ -4742,9 +4813,11 @@ vim.wo.pvw = vim.wo.previewwindow --- It is possible to override the level for individual highlights within --- the popupmenu using `highlight-blend`. For instance, to enable --- transparency but force the current selected element to be fully opaque: ---- ``` ---- :set pumblend=15 ---- :hi PmenuSel blend=0 +--- +--- ```vim +--- +--- set pumblend=15 +--- hi PmenuSel blend=0 --- ``` --- --- UI-dependent. Works best with RGB colors. 'termguicolors' @@ -5015,8 +5088,9 @@ vim.go.ru = vim.go.ruler --- The default ruler width is 17 characters. To make the ruler 15 --- characters wide, put "%15(" at the start and "%)" at the end. --- Example: ---- ``` ---- :set rulerformat=%15(%c%V\ %p%%%) +--- +--- ```vim +--- set rulerformat=%15(%c%V\ %p%%%) --- ``` --- --- @@ -5083,8 +5157,9 @@ vim.go.ruf = vim.go.rulerformat --- wildcards. --- See `:runtime`. --- Example: ---- ``` ---- :set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME +--- +--- ```vim +--- set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME --- ``` --- This will use the directory "~/vimruntime" first (containing your --- personal Nvim runtime files), then "/mygroup/vim", and finally @@ -5165,7 +5240,8 @@ vim.go.sj = vim.go.scrolljump --- when long lines wrap). --- After using the local value, go back the global value with one of --- these two: ---- ``` +--- +--- ```vim --- setlocal scrolloff< --- setlocal scrolloff=-1 --- ``` @@ -5394,8 +5470,9 @@ vim.go.ssop = vim.go.sessionoptions --- contents size) = 10253 bytes. --- --- Example: ---- ``` ---- :set shada='50,<1000,s100,:0,n~/nvim/shada +--- +--- ```vim +--- set shada='50,<1000,s100,:0,n~/nvim/shada --- ``` --- --- '50 Marks will be remembered for the last 50 files you @@ -5446,14 +5523,16 @@ vim.go.sdf = vim.go.shadafile --- --- If the name of the shell contains a space, you need to enclose it in --- quotes. Example with quotes: ---- ``` ---- :set shell=\"c:\program\ files\unix\sh.exe\"\ -f +--- +--- ```vim +--- set shell=\"c:\program\ files\unix\sh.exe\"\ -f --- ``` --- Note the backslash before each quote (to avoid starting a comment) and --- each space (to avoid ending the option value), so better use `:let-&` --- like this: ---- ``` ---- :let &shell='"C:\Program Files\unix\sh.exe" -f' +--- +--- ```vim +--- let &shell='"C:\Program Files\unix\sh.exe" -f' --- ``` --- Also note that the "-f" is not inside the quotes, because it is not --- part of the command name. @@ -5478,7 +5557,8 @@ vim.go.sdf = vim.go.shadafile --- unescaping, so to keep yourself sane use `:let-&` like shown above. --- *shell-powershell* --- To use PowerShell: ---- ``` +--- +--- ```vim --- let &shell = executable('pwsh') ? 'pwsh' : 'powershell' --- let &shellcmdflag = '-NoLogo -ExecutionPolicy RemoteSigned -Command [Console]::InputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new();$PSDefaultParameterValues[''Out-File:Encoding'']=''utf8'';Remove-Alias -Force -ErrorAction SilentlyContinue tee;' --- let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode' @@ -5603,7 +5683,8 @@ vim.go.srr = vim.go.shellredir --- any file for best results. This might change in the future. --- 'shellslash' only works when a backslash can be used as a path --- separator. To test if this is so use: ---- ``` +--- +--- ```vim --- if exists('+shellslash') --- ``` --- Also see 'completeslash'. @@ -5739,9 +5820,10 @@ vim.go.shm = vim.go.shortmess --- String to put at the start of lines that have been wrapped. Useful --- values are "> " or "+++ ": ---- ``` ---- :let &showbreak = "> " ---- :let &showbreak = '+++ ' +--- +--- ```vim +--- let &showbreak = "> " +--- let &showbreak = '+++ ' --- ``` --- Only printable single-cell characters are allowed, excluding and --- comma (in a future version the comma might be used to separate the @@ -5752,8 +5834,9 @@ vim.go.shm = vim.go.shortmess --- "n" flag to 'cpoptions'. --- A window-local value overrules a global value. If the global value is --- set and you want no value in the current window use NONE: ---- ``` ---- :setlocal showbreak=NONE +--- +--- ```vim +--- setlocal showbreak=NONE --- ``` --- --- @@ -5885,7 +5968,8 @@ vim.go.ss = vim.go.sidescroll --- close to the beginning of the line. --- After using the local value, go back the global value with one of --- these two: ---- ``` +--- +--- ```vim --- setlocal sidescrolloff< --- setlocal sidescrolloff=-1 --- ``` @@ -5893,9 +5977,11 @@ vim.go.ss = vim.go.sidescroll --- Example: Try this together with 'sidescroll' and 'listchars' as --- in the following example to never allow the cursor to move --- onto the "extends" character: ---- ``` ---- :set nowrap sidescroll=1 listchars=extends:>,precedes:< ---- :set sidescrolloff=1 +--- +--- ```vim +--- +--- set nowrap sidescroll=1 listchars=extends:>,precedes:< +--- set sidescrolloff=1 --- ``` --- --- @@ -6076,7 +6162,8 @@ vim.bo.spf = vim.bo.spellfile --- A comma-separated list of word list names. When the 'spell' option is --- on spellchecking will be done for these languages. Example: ---- ``` +--- +--- ```vim --- set spelllang=en_us,nl,medical --- ``` --- This means US English, Dutch and medical words are recognized. Words @@ -6194,8 +6281,9 @@ vim.bo.spo = vim.bo.spelloptions --- --- Only one of "best", "double" or "fast" may be used. The others may --- appear several times in any order. Example: ---- ``` ---- :set sps=file:~/.config/nvim/sugg,best,expr:MySuggest() +--- +--- ```vim +--- set sps=file:~/.config/nvim/sugg,best,expr:MySuggest() --- ``` --- --- This option cannot be set from a `modeline` or in the `sandbox`, for @@ -6293,21 +6381,21 @@ vim.go.sol = vim.go.startofline --- --- ```vim --- " Relative number with bar separator and click handlers: ---- :set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T +--- set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T --- --- " Right aligned relative cursor line number: ---- :let &stc='%=%{v:relnum?v:relnum:v:lnum} ' +--- let &stc='%=%{v:relnum?v:relnum:v:lnum} ' --- --- " Line numbers in hexadecimal for non wrapped part of lines: ---- :let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' +--- let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' --- --- " Human readable line numbers with thousands separator: ---- :let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' +--- let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' --- . '%(\\d\\d\\d\\)\\+$",",","g")}' --- --- " Both relative and absolute line numbers with different --- " highlighting for odd and even relative numbers: ---- :let &stc='%#NonText#%{&nu?v:lnum:""}' . +--- let &stc='%#NonText#%{&nu?v:lnum:""}' . --- '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' . --- '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}' --- ``` @@ -6331,8 +6419,9 @@ vim.wo.stc = vim.wo.statuscolumn --- --- When the option starts with "%!" then it is used as an expression, --- evaluated and the result is used as the option value. Example: ---- ``` ---- :set statusline=%!MyStatusLine() +--- +--- ```vim +--- set statusline=%!MyStatusLine() --- ``` --- The *g:statusline_winid* variable will be set to the `window-ID` of the --- window that the status line belongs to. @@ -6415,7 +6504,8 @@ vim.wo.stc = vim.wo.statuscolumn --- The expression can contain the "}" character, the end of --- expression is denoted by "%}". --- For example: ---- ``` +--- +--- ```vim --- func! Stl_filename() abort --- return "%t" --- endfunc @@ -6484,8 +6574,9 @@ vim.wo.stc = vim.wo.statuscolumn --- not set) and a minwid is not set for the group, the whole group will --- become empty. This will make a group like the following disappear --- completely from the statusline when none of the flags are set. ---- ``` ---- :set statusline=...%(\ [%M%R%H]%)... +--- +--- ```vim +--- set statusline=...%(\ [%M%R%H]%)... --- ``` --- Beware that an expression is evaluated each and every time the status --- line is displayed. @@ -6518,35 +6609,42 @@ vim.wo.stc = vim.wo.statuscolumn --- --- Examples: --- Emulate standard status line with 'ruler' set ---- ``` ---- :set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P +--- +--- ```vim +--- set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P --- ``` --- Similar, but add ASCII value of char under the cursor (like "ga") ---- ``` ---- :set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P +--- +--- ```vim +--- set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P --- ``` --- Display byte count and byte value, modified flag in red. ---- ``` ---- :set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b' ---- :hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red +--- +--- ```vim +--- set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b' +--- hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red --- ``` --- Display a ,GZ flag if a compressed file is loaded ---- ``` ---- :set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h... +--- +--- ```vim +--- set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h... --- ``` --- In the `:autocmd`'s: ---- ``` ---- :let b:gzflag = 1 +--- +--- ```vim +--- let b:gzflag = 1 --- ``` --- And: ---- ``` ---- :unlet b:gzflag +--- +--- ```vim +--- unlet b:gzflag --- ``` --- And define this function: ---- ``` ---- :function VarExists(var, val) ---- : if exists(a:var) | return a:val | else | return '' | endif ---- :endfunction +--- +--- ```vim +--- function VarExists(var, val) +--- if exists(a:var) | return a:val | else | return '' | endif +--- endfunction --- ``` --- --- @@ -6577,8 +6675,9 @@ vim.go.su = vim.go.suffixes --- Comma-separated list of suffixes, which are used when searching for a --- file for the "gf", "[I", etc. commands. Example: ---- ``` ---- :set suffixesadd=.java +--- +--- ```vim +--- set suffixesadd=.java --- ``` --- --- @@ -6663,26 +6762,26 @@ vim.bo.smc = vim.bo.synmaxcol --- Otherwise this option does not always reflect the current syntax (the --- b:current_syntax variable does). --- This option is most useful in a modeline, for a file which syntax is ---- not automatically recognized. Example, in an IDL file: ---- ``` +--- not automatically recognized. Example, in an IDL file: >c --- /* vim: set syntax=idl : */ --- ``` --- When a dot appears in the value then this separates two filetype ---- names. Example: ---- ``` +--- names. Example: >c --- /* vim: set syntax=c.doxygen : */ --- ``` --- This will use the "c" syntax first, then the "doxygen" syntax. --- Note that the second one must be prepared to be loaded as an addition, --- otherwise it will be skipped. More than one dot may appear. --- To switch off syntax highlighting for the current file, use: ---- ``` ---- :set syntax=OFF +--- +--- ```vim +--- set syntax=OFF --- ``` --- To switch syntax highlighting on according to the current value of the --- 'filetype' option: ---- ``` ---- :set syntax=ON +--- +--- ```vim +--- set syntax=ON --- ``` --- What actually happens when setting the 'syntax' option is that the --- Syntax autocommand event is triggered with the value as argument. @@ -7112,15 +7211,17 @@ vim.go.titleold = vim.o.titleold --- This option cannot be set in a modeline when 'modelineexpr' is off. --- --- Example: ---- ``` ---- :auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") ---- :set title titlestring=%<%F%=%l/%L-%P titlelen=70 +--- +--- ```vim +--- auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") +--- set title titlestring=%<%F%=%l/%L-%P titlelen=70 --- ``` --- The value of 'titlelen' is used to align items in the middle or right --- of the available space. --- Some people prefer to have the file name first: ---- ``` ---- :set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) +--- +--- ```vim +--- set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) --- ``` --- Note the use of "%{ }" and an expression to get the path of the file, --- without the file name. The "%( %)" constructs are used to add a @@ -7205,7 +7306,8 @@ vim.bo.udf = vim.bo.undofile --- Nevertheless, a single change can already use a large amount of memory. --- Set to 0 for Vi compatibility: One level of undo and "u" undoes --- itself: ---- ``` +--- +--- ```vim --- set ul=0 --- ``` --- But you can also get Vi compatibility by including the 'u' flag in @@ -7213,7 +7315,8 @@ vim.bo.udf = vim.bo.undofile --- Also see `undo-two-ways`. --- Set to -1 for no undo at all. You might want to do this only for the --- current buffer: ---- ``` +--- +--- ```vim --- setlocal ul=-1 --- ``` --- This helps when you run out of memory for a single change. @@ -7285,8 +7388,9 @@ vim.go.ut = vim.go.updatetime --- For example, when editing assembly language files where statements --- start in the 9th column and comments in the 41st, it may be useful --- to use the following: ---- ``` ---- :set varsofttabstop=8,32,8 +--- +--- ```vim +--- set varsofttabstop=8,32,8 --- ``` --- This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more --- for every column thereafter. @@ -7303,8 +7407,9 @@ vim.bo.vsts = vim.bo.varsofttabstop --- A list of the number of spaces that a in the file counts for, --- separated by commas. Each value corresponds to one tab, with the --- final value applying to all subsequent tabs. For example: ---- ``` ---- :set vartabstop=4,20,10,8 +--- +--- ```vim +--- set vartabstop=4,20,10,8 --- ``` --- This will make the first tab 4 spaces wide, the second 20 spaces, --- the third 10 spaces, and all following tabs 8 spaces. @@ -7459,8 +7564,9 @@ vim.go.warn = vim.o.warn --- [ Insert and Replace --- ] Insert and Replace --- For example: ---- ``` ---- :set ww=<,>,[,] +--- +--- ```vim +--- set ww=<,>,[,] --- ``` --- allows wrap only when cursor keys are used. --- When the movement keys are used in combination with a delete or change @@ -7489,8 +7595,9 @@ vim.go.ww = vim.go.whichwrap --- can be used, but hitting it twice in a row will still exit --- command-line as a failsafe measure. --- Although 'wc' is a number option, you can set it to a special key: ---- ``` ---- :set wc= +--- +--- ```vim +--- set wc= --- ``` --- --- @@ -7505,9 +7612,10 @@ vim.go.wc = vim.go.wildchar --- keys suitable for this option by looking at `ex-edit-index`. Normally --- you'll never actually type 'wildcharm', just use it in mappings that --- automatically invoke completion mode, e.g.: ---- ``` ---- :set wcm= ---- :cnoremap ss so $vim/sessions/*.vim +--- +--- ```vim +--- set wcm= +--- cnoremap ss so $vim/sessions/*.vim --- ``` --- Then after typing :ss you can use CTRL-P & CTRL-N. --- @@ -7524,8 +7632,9 @@ vim.go.wcm = vim.go.wildcharm --- The pattern is used like with `:autocmd`, see `autocmd-pattern`. --- Also see 'suffixes'. --- Example: ---- ``` ---- :set wildignore=*.o,*.obj +--- +--- ```vim +--- set wildignore=*.o,*.obj --- ``` --- The use of `:set+=` and `:set-=` is preferred when adding or removing --- a pattern from the list. This avoids problems when a future version @@ -7581,9 +7690,10 @@ vim.go.wic = vim.go.wildignorecase --- --- If you want and to move the cursor instead of selecting --- a different match, use this: ---- ``` ---- :cnoremap ---- :cnoremap +--- +--- ```vim +--- cnoremap +--- cnoremap --- ``` --- --- `hl-WildMenu` highlights the current match. @@ -7626,24 +7736,29 @@ vim.go.wmnu = vim.go.wildmenu --- current buffer). --- --- Examples: ---- ``` ---- :set wildmode=full +--- +--- ```vim +--- set wildmode=full --- ``` --- Complete first full match, next match, etc. (the default) ---- ``` ---- :set wildmode=longest,full +--- +--- ```vim +--- set wildmode=longest,full --- ``` --- Complete longest common string, then each full match ---- ``` ---- :set wildmode=list:full +--- +--- ```vim +--- set wildmode=list:full --- ``` --- List all matches and complete each full match ---- ``` ---- :set wildmode=list,full +--- +--- ```vim +--- set wildmode=list,full --- ``` --- List all matches without completing, then each full match ---- ``` ---- :set wildmode=longest,list +--- +--- ```vim +--- set wildmode=longest,list --- ``` --- Complete longest common string, then list alternatives. --- More info here: `cmdline-completion`. @@ -7781,7 +7896,8 @@ vim.wo.wfw = vim.wo.winfixwidth --- that ":all" will create only two windows. To avoid "vim -o 1 2 3 4" --- to create only two windows, set the option after startup is done, --- using the `VimEnter` event: ---- ``` +--- +--- ```vim --- au VimEnter * set winheight=999 --- ``` --- Minimum value is 1. @@ -7811,7 +7927,8 @@ vim.go.wh = vim.go.winheight --- message area cannot be overridden. --- --- Example: show a different color for non-current windows: ---- ``` +--- +--- ```vim --- set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC --- ``` --- @@ -7881,9 +7998,10 @@ vim.go.wiw = vim.go.winwidth --- The line will be broken in the middle of a word if necessary. See --- 'linebreak' to get the break at a word boundary. --- To make scrolling horizontally a bit more useful, try this: ---- ``` ---- :set sidescroll=5 ---- :set listchars+=precedes:<,extends:> +--- +--- ```vim +--- set sidescroll=5 +--- set listchars+=precedes:<,extends:> --- ``` --- See 'sidescroll', 'listchars' and `wrap-off`. --- This option can't be set from a `modeline` when the 'diff' option is -- cgit From e8acbc1ade5082563a9464ed3d1225414723390d Mon Sep 17 00:00:00 2001 From: bfredl Date: Fri, 6 Oct 2023 23:01:24 +0200 Subject: refactor(cpoptions): remove 'p' Deleting a cpo flag a day keeps the doctor away We don't need two different ways to indent LISP code --- runtime/lua/vim/_meta/options.lua | 3 --- 1 file changed, 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 209c27cfd8..46497179ac 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -1296,9 +1296,6 @@ vim.bo.ci = vim.bo.copyindent --- when it didn't exist when editing it. This is a --- protection against a file unexpectedly created by --- someone else. Vi didn't complain about this. ---- *cpo-p* ---- p Vi compatible Lisp indenting. When not present, a ---- slightly better algorithm is used. --- *cpo-P* --- P When included, a ":write" command that appends to a --- file will set the file name for the current buffer, if -- cgit From bbd5c6363c25e8fbbfb962f8f6c5ea1800d431ca Mon Sep 17 00:00:00 2001 From: luukvbaal Date: Tue, 26 Dec 2023 00:16:03 +0100 Subject: feat(extmarks): add virt_text_repeat_linebreak flag (#26625) Problem: Unable to predict which byte-offset to place virtual text to make it repeat visually in the wrapped part of a line. Solution: Add a flag to nvim_buf_set_extmark() that causes virtual text to repeat in wrapped lines. --- runtime/lua/vim/_meta/api.lua | 2 ++ runtime/lua/vim/_meta/api_keysets.lua | 1 + 2 files changed, 3 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index c8c3e1c3af..ba18a16488 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -519,6 +519,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- text is selected or hidden because of scrolling with --- 'nowrap' or 'smoothscroll'. Currently only affects --- "overlay" virt_text. +--- • virt_text_repeat_linebreak : repeat the virtual text on +--- wrapped lines. --- • hl_mode : control how highlights are combined with the --- highlights of the text. Currently only affects virt_text --- highlights, but might affect `hl_group` in later versions. diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 4ec8b03d30..bb1031b2fa 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -251,6 +251,7 @@ error('Cannot require a meta file') --- @field virt_text_pos? string --- @field virt_text_win_col? integer --- @field virt_text_hide? boolean +--- @field virt_text_repeat_linebreak? boolean --- @field hl_eol? boolean --- @field hl_mode? string --- @field invalidate? boolean -- cgit From 714b075197c02d27d5c05133759ae97bed279b50 Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Thu, 28 Dec 2023 03:28:48 +0100 Subject: docs: small fixes (#26651) Co-authored-by: Gregory Anders Co-authored-by: WillLillis --- runtime/lua/vim/_meta/api.lua | 1 - 1 file changed, 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index ba18a16488..d94cef481e 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1493,7 +1493,6 @@ function vim.api.nvim_open_term(buffer, opts) end --- ```lua --- vim.api.nvim_open_win(0, false, --- {relative='win', width=12, height=3, bufpos={100,10}}) ---- }) --- ``` --- --- @param buffer integer Buffer to display, or 0 for current buffer -- cgit From 53a3e6ac879d89039c69d3e44f46ed9bf857a9d9 Mon Sep 17 00:00:00 2001 From: xvzc <45588457+xvzc@users.noreply.github.com> Date: Thu, 28 Dec 2023 20:13:46 +0900 Subject: docs(eval): add parameter type for vim.fn.mode() (#26776) --- runtime/lua/vim/_meta/vimfn.lua | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 59d9836688..02e794ce10 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -5829,8 +5829,9 @@ function vim.fn.mkdir(name, flags, prot) end --- the leading character(s). --- Also see |visualmode()|. --- +--- @param expr? any --- @return any -function vim.fn.mode() end +function vim.fn.mode(expr) end --- Convert a list of Vimscript objects to msgpack. Returned value is a --- |readfile()|-style list. When {type} contains "B", a |Blob| is -- cgit From 6fa0f303d7f0823bfc5ba6cc7b4e7a7cd76143ac Mon Sep 17 00:00:00 2001 From: altermo Date: Sun, 31 Dec 2023 14:08:16 +0100 Subject: fix(builtin): parameter mismatch between winsaveview and winrestview --- runtime/lua/vim/_meta/builtin_types.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua index ef0452c649..e74cf86173 100644 --- a/runtime/lua/vim/_meta/builtin_types.lua +++ b/runtime/lua/vim/_meta/builtin_types.lua @@ -118,7 +118,7 @@ --- @field topfill? integer --- @field topline? integer ---- @class vim.fn.winsaveview.ret +--- @class vim.fn.winsaveview.ret: vim.fn.winrestview.dict --- @field col integer --- @field coladd integer --- @field curswant integer -- cgit From 3faace199583f3a36470b717ce3e386e476f3a30 Mon Sep 17 00:00:00 2001 From: Jaehwang Jung Date: Thu, 7 Dec 2023 21:01:50 +0900 Subject: docs: clarify on_bytes arguments based on extmark_splice doc --- runtime/lua/vim/_meta/api.lua | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index d94cef481e..c0dfa7635b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -173,11 +173,15 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- • start column of the changed text --- • byte offset of the changed text (from the start of --- the buffer) ---- • old end row of the changed text ---- • old end column of the changed text +--- • old end row of the changed text (offset from start +--- row) +--- • old end column of the changed text (if old end row +--- = 0, offset from start column) --- • old end byte length of the changed text ---- • new end row of the changed text ---- • new end column of the changed text +--- • new end row of the changed text (offset from start +--- row) +--- • new end column of the changed text (if new end row +--- = 0, offset from start column) --- • new end byte length of the changed text --- --- • on_changedtick: Lua callback invoked on changedtick -- cgit From 4e9298ecdf945b4d16c2c6e6e4ed82b97880917c Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Thu, 28 Dec 2023 17:50:05 -0500 Subject: refactor(gen_vimdoc): generate function doc from metadata, not from xml Problem: For function definitions to be included in the vimdoc (formatted) and to be exported as mpack data (unformatted), we had two internal representations of the same function/API metadata in duplicate; one is FunctionDoc (which was previously a dict), and the other is doxygen XML DOM from which vimdoc (functions sections) was generated. Solution: We should have a single path and unified data representation (i.e. FunctionDoc) that contains all the metadata and information about function APIs, from which both of mpack export and vimdoc are generated. I.e., vimdocs are no longer generated directly from doxygen XML nodes, but generated via: (XML DOM Nodes) ------------> FunctionDoc ------> mpack (unformatted) Recursive Internal | Formatting Metadata +---> vimdoc (formatted) This refactoring eliminates the hacky and ugly use of `fmt_vimhelp` in `fmt_node_as_vimhelp()` and all other helper functions! This way, `fmt_node_as_vimhelp()` can simplified as it no longer needs to handle generating of function docs, which needs to be done only in the topmost level of recursion. --- runtime/lua/vim/_meta/api.lua | 3 +++ 1 file changed, 3 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index c0dfa7635b..b6ce3fce8a 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -73,6 +73,9 @@ function vim.api.nvim__id_dictionary(dct) end function vim.api.nvim__id_float(flt) end --- @private +--- NB: if your UI doesn't use hlstate, this will not return hlstate first +--- time. +--- --- @param grid integer --- @param row integer --- @param col integer -- cgit From dc48a98f9ac614dc94739637c967aa29e064807e Mon Sep 17 00:00:00 2001 From: Jaehwang Jung Date: Mon, 25 Dec 2023 02:31:47 +0900 Subject: fix(decorations): validate botline for on_win Problem: Many decoration providers (treesitter injection highlighting, semantic token highlighting, inlay hint) rely on the correctness of the `botline` argument of `on_win` callback. However, `botline` can be smaller than the actual line number of the last displayed line if some lines are folded. In such cases, some decorations will be missing in the lines not covered by `botline`. Solution: Validate `botline` when invoking `on_win`. NOTE: It seems that the old code was deliberately avoiding this presumably due to performance reasons. However, I haven't experienced noticeable lag after this change, and I believe the cost of botline computation would be much smaller than the cost of decoration providers. --- runtime/lua/vim/_meta/api.lua | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index c0dfa7635b..02128b66b9 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1761,9 +1761,7 @@ function vim.api.nvim_set_current_win(window) end --- • on_buf: called for each buffer being redrawn (before window --- callbacks) ["buf", bufnr, tick] --- • on_win: called when starting to redraw a specific window. ---- botline_guess is an approximation that does not exceed the ---- last line number. ["win", winid, bufnr, topline, ---- botline_guess] +--- ["win", winid, bufnr, topline, botline] --- • on_line: called for each buffer line being redrawn. (The --- interaction with fold lines is subject to change) ["win", --- winid, bufnr, row] -- cgit From fa61e0c047954e7eb494ee02144a4dc71a42b3b2 Mon Sep 17 00:00:00 2001 From: Luuk van Baal Date: Mon, 1 Jan 2024 14:24:48 +0100 Subject: refactor(column): define and use maximum 'statuscolumn' width Problem: The maximum 'statuscolumn' width and grow behavior is undocumented. Solution: Define, use and document the maximum 'statuscolumn' width and grow behavior. --- runtime/lua/vim/_meta/options.lua | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 46497179ac..7ad720b6b2 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6359,9 +6359,13 @@ vim.go.sol = vim.go.startofline --- %s sign column for currently drawn line --- %C fold column for currently drawn line --- ---- NOTE: To draw the sign and fold columns, their items must be included in ---- 'statuscolumn'. Even when they are not included, the status column width ---- will adapt to the 'signcolumn' and 'foldcolumn' width. +--- The 'statuscolumn' width follows that of the default columns and +--- adapts to the `'numberwidth'`, `'signcolumn'` and `'foldcolumn'` option +--- values (regardless of whether the sign and fold items are present). +--- Aditionally, the 'statuscolumn' grows with the size of the evaluated +--- format string, up to a point (following the maximum size of the default +--- fold, sign and number columns). Shrinking only happens when the number +--- of lines in a buffer changes, or the 'statuscolumn' option is set. --- --- The `v:lnum` variable holds the line number to be drawn. --- The `v:relnum` variable holds the relative line number to be drawn. -- cgit From dab584408211a39962a7313b7b8c4cb7e3717a7a Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 5 Jan 2024 08:23:51 +0800 Subject: vim-patch:9.1.0010: Keymap completion is not available (#26888) Problem: Keymap completion is not available Solution: Add keymap completion (Doug Kearns) Add keymap completion to the 'keymap' option, user commands and builtin completion functions. closes: vim/vim#13692 https://github.com/vim/vim/commit/81642d9d6ff5cd6a90a012b1b98632ce51eeb1a8 Co-authored-by: Doug Kearns --- runtime/lua/vim/_meta/vimfn.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 02e794ce10..a763be93b9 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -2889,6 +2889,7 @@ function vim.fn.getcmdwintype() end --- help help subjects --- highlight highlight groups --- history |:history| suboptions +--- keymap keyboard mappings --- locale locale names (as output of locale -a) --- mapclear buffer argument --- mapping mapping name -- cgit From f40df63bdca33d343cada6ceaafbc8b765ed7cc6 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Thu, 4 Jan 2024 11:09:13 -0500 Subject: fix(docs): make lines not overflow in vim docs Problem: Some lines in the generated vim doc are overflowing, not correctly wrapped at 78 characters. This happens when docs body contains several consecutive 'inline' elements generated by doxygen. Solution: Take into account the current column offset of the last line, and prepend some padding before doc_wrap(). --- runtime/lua/vim/_meta/api.lua | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index e85f81f5f9..19039eb226 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -155,7 +155,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return `true` to detach. Args: +--- • on_lines: Lua callback invoked on change. Return `true` to +--- detach. Args: --- • the string "lines" --- • buffer handle --- • b:changedtick @@ -168,7 +169,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- --- • on_bytes: Lua callback invoked on change. This --- callback receives more granular information about the ---- change compared to on_lines. Return `true` to detach. Args: +--- change compared to on_lines. Return `true` to +--- detach. Args: --- • the string "bytes" --- • buffer handle --- • b:changedtick @@ -530,7 +532,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- wrapped lines. --- • hl_mode : control how highlights are combined with the --- highlights of the text. Currently only affects virt_text ---- highlights, but might affect `hl_group` in later versions. +--- highlights, but might affect `hl_group` in +--- later versions. --- • "replace": only show the virt_text color. This is the --- default. --- • "combine": combine with background text color. @@ -740,7 +743,8 @@ function vim.api.nvim_chan_send(chan, data) end --- • 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. +--- • NOTE: If not passed, will only delete autocmds not in any +--- group. function vim.api.nvim_clear_autocmds(opts) end --- Executes an Ex command. @@ -808,7 +812,9 @@ function vim.api.nvim_complete_set(index, opts) end --- @return integer function vim.api.nvim_create_augroup(name, opts) end ---- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). +--- 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 @@ -1525,8 +1531,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- • height: Window height (in character cells). Minimum of 1. --- • bufpos: Places float relative to buffer text (only when --- relative="win"). Takes a tuple of zero-indexed [line, ---- column]. `row` and `col` if given are applied relative to this position, else they ---- default to: +--- column]. `row` and `col` if given are +--- applied relative to this position, else they default to: --- • `row=1` and `col=0` if `anchor` is "NW" or "NE" --- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus --- like a tooltip near the buffer text). @@ -1541,8 +1547,9 @@ function vim.api.nvim_open_term(buffer, opts) end --- • external: GUI should display the window as an external --- top-level window. Currently accepts no other positioning --- configuration together with this. ---- • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must be larger ---- than zero. The following screen elements have hard-coded +--- • zindex: Stacking order. floats with higher `zindex` go on +--- top on floats with lower indices. Must be larger than +--- zero. The following screen elements have hard-coded --- z-indices: --- • 100: insert completion popupmenu --- • 200: message scrollback @@ -1661,7 +1668,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- @param data string Multiline input. May be binary (containing NUL bytes). --- @param crlf boolean Also break lines at CR and CRLF. --- @param phase integer -1: paste in a single call (i.e. without streaming). To ---- "stream" a paste, call `nvim_paste` sequentially with these `phase` values: +--- "stream" a paste, call `nvim_paste` sequentially +--- with these `phase` values: --- • 1: starts the paste (exactly once) --- • 2: continues the paste (zero or more times) --- • 3: ends the paste (exactly once) -- cgit From beca827212b106114c371f8bb61aa1a50810062f Mon Sep 17 00:00:00 2001 From: Ghjuvan Lacambre Date: Tue, 9 Jan 2024 15:27:56 +0100 Subject: feat(terminal): trigger TermRequest autocommand events (#22159) This commit implements a new TermRequest autocommand event and has Neovim emit this event when children of terminal buffers emit an OSC or DCS sequence libvterm does not handle. The TermRequest autocommand event has additional data in the v:termrequest variable. Co-authored-by: Gregory Anders --- runtime/lua/vim/_meta/vvars.lua | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index e3b89aeff7..ca87fb9d15 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -687,11 +687,18 @@ vim.v.t_number = ... --- @type integer vim.v.t_string = ... ---- The value of the most recent OSC or DCS escape sequence +--- The value of the most recent OSC or DCS control sequence +--- sent from a process running in the embedded `terminal`. +--- This can be read in a `TermRequest` event handler to respond +--- to queries from embedded applications. +--- @type string +vim.v.termrequest = ... + +--- The value of the most recent OSC or DCS control sequence --- received by Nvim from the terminal. This can be read in a --- `TermResponse` event handler after querying the terminal using --- another escape sequence. ---- @type any +--- @type string vim.v.termresponse = ... --- Must be set before using `test_garbagecollect_now()`. -- cgit From 2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 9 Jan 2024 17:36:46 +0000 Subject: fix(doc): improve doc generation of types using lpeg Added a lpeg grammar for LuaCATS and use it in lua2dox.lua --- runtime/lua/vim/_meta/api.lua | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 19039eb226..3f06d4fd43 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -812,9 +812,8 @@ function vim.api.nvim_complete_set(index, opts) end --- @return integer function vim.api.nvim_create_augroup(name, opts) end ---- Creates an `autocommand` event handler, defined by `callback` (Lua ---- function or Vimscript function name string) or `command` (Ex command ---- string). +--- 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 -- cgit From 2bdd8fad4cf4008125ce540453434888c07044a6 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Sun, 14 Jan 2024 08:44:16 +0800 Subject: docs(builtin): fix mapset() signature (#27008) --- runtime/lua/vim/_meta/vimfn.lua | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index a763be93b9..f044871601 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -5152,6 +5152,12 @@ function vim.fn.maplist() end --- @return any function vim.fn.mapnew(expr1, expr2) end +--- @param mode string +--- @param abbr? any +--- @param dict? any +--- @return any +function vim.fn.mapset(mode, abbr, dict) end + --- Restore a mapping from a dictionary, possibly returned by --- |maparg()| or |maplist()|. A buffer mapping, when dict.buffer --- is true, is set on the current buffer; it is up to the caller @@ -5187,11 +5193,9 @@ function vim.fn.mapnew(expr1, expr2) end --- call mapset(d) --- endfor --- ---- @param mode string ---- @param abbr? any ---- @param dict? any +--- @param dict any --- @return any -function vim.fn.mapset(mode, abbr, dict) end +function vim.fn.mapset(dict) end --- When {expr} is a |List| then this returns the index of the --- first item where {pat} matches. Each item is used as a -- cgit From 2cdea852e8934beb89012f2127f333e4dd8aada8 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Thu, 11 Jan 2024 12:24:44 -0500 Subject: docs: auto-generate docs for `vim.lpeg` and `vim.re` - Add section `VIM.LPEG` and `VIM.RE` to docs/lua.txt. - Add `_meta/re.lua` which adds luadoc and type annotations, for the vendored `vim.re` package. - Fix minor style issues on `_meta/lpeg.lua` luadoc for better vimdocs generation. - Fix a bug on `gen_vimdoc` where non-helptags in verbatim code blocks were parsed as helptags, affecting code examples on `vim.lpeg.Cf`, etc. - Also move the `vim.regex` section below so that it can be located closer to `vim.lpeg` and `vim.re`. --- runtime/lua/vim/_meta/lpeg.lua | 32 +++++++++++++++++++++--- runtime/lua/vim/_meta/re.lua | 57 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+), 3 deletions(-) create mode 100644 runtime/lua/vim/_meta/re.lua (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 42c9a6449e..5bd502a7c8 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -1,7 +1,24 @@ --- @meta +error('Cannot require a meta file') --- These types were taken from https://github.com/LuaCATS/lpeg, with types being renamed to include --- the vim namespace and with some descriptions made less verbose. +-- These types were taken from https://github.com/LuaCATS/lpeg +-- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) +-- with types being renamed to include the vim namespace and with some descriptions made less verbose. + +---@defgroup vim.lpeg +---
help
+---LPeg is a pattern-matching library for Lua, based on
+---Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+---
+---                                                                    *lua-lpeg*
+---                                                            *vim.lpeg.Pattern*
+---The LPeg library for parsing expression grammars is included as `vim.lpeg`
+---(https://www.inf.puc-rio.br/~roberto/lpeg/).
+---
+---In addition, its regex-like interface is available as |vim.re|
+---(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+---
+---
--- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs). vim.lpeg = {} @@ -32,6 +49,7 @@ local Pattern = {} --- matches anywhere. --- --- Example: +--- --- ```lua --- local pattern = lpeg.R("az") ^ 1 * -1 --- assert(pattern:match("hello") == 6) @@ -55,6 +73,7 @@ function vim.lpeg.match(pattern, subject, init) end --- 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) @@ -69,7 +88,7 @@ function Pattern:match(subject, init) end --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`. --- ---- @return 'pattern'|nil +--- @return "pattern"|nil function vim.lpeg.type(value) end --- Returns a string with the running version of LPeg. @@ -115,6 +134,7 @@ function vim.lpeg.B(pattern) end --- `lpeg.R("az", "AZ")` matches any ASCII letter. --- --- Example: +--- --- ```lua --- local pattern = lpeg.R("az") ^ 1 * -1 --- assert(pattern:match("hello") == 6) @@ -137,6 +157,7 @@ function vim.lpeg.S(string) end --- 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) @@ -168,6 +189,7 @@ function vim.lpeg.V(v) end --- that table. --- --- Example: +--- --- ```lua --- lpeg.locale(lpeg) --- local space = lpeg.space^0 @@ -191,6 +213,7 @@ function vim.lpeg.locale(tab) end --- The captured value is a string. If `patt` has other captures, their values are returned after this one. --- --- Example: +--- --- ```lua --- local function split (s, sep) --- sep = lpeg.P(sep) @@ -241,6 +264,7 @@ function vim.lpeg.Cc(...) end --- becomes the captured value. --- --- Example: +--- --- ```lua --- local number = lpeg.R("09") ^ 1 / tonumber --- local list = number * ("," * number) ^ 0 @@ -267,6 +291,7 @@ function vim.lpeg.Cg(patt, name) end --- 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 @@ -285,6 +310,7 @@ function vim.lpeg.Cp() end --- value is the string resulting from all replacements. --- --- Example: +--- --- ```lua --- local function gsub (s, patt, repl) --- patt = lpeg.P(patt) diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua new file mode 100644 index 0000000000..4f254b19a0 --- /dev/null +++ b/runtime/lua/vim/_meta/re.lua @@ -0,0 +1,57 @@ +--- @meta +error('Cannot require a meta file') + +-- Documentations and Lua types for vim.re (vendored re.lua, lpeg-1.1.0) +-- https://www.inf.puc-rio.br/~roberto/lpeg/re.html +-- +-- Copyright © 2007-2023 Lua.org, PUC-Rio. +-- See 'lpeg.html' for license + +--- @defgroup vim.re +---
help
+---The `vim.re` module provides a conventional regex-like syntax for pattern usage
+---within LPeg |vim.lpeg|.
+---
+---See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
+---documentation including regex syntax and more concrete examples.
+---
+---
+ +--- 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. +--- @param string string +--- @param defs? table +--- @return vim.lpeg.Pattern +function vim.re.compile(string, defs) end + +--- 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. +--- @param subject string +--- @param pattern vim.lpeg.Pattern|string +--- @param init? integer +--- @return integer|nil the index where the occurrence starts, nil if no match +--- @return integer|nil the index where the occurrence ends, nil if no match +function vim.re.find(subject, pattern, init) end + +--- Does a global substitution, replacing all occurrences of {pattern} in the given {subject} by +--- {replacement}. +--- @param subject string +--- @param pattern vim.lpeg.Pattern|string +--- @param replacement string +--- @return string +function vim.re.gsub(subject, pattern, replacement) end + +--- Matches the given {pattern} against the given {subject}, returning all captures. +--- @param subject string +--- @param pattern vim.lpeg.Pattern|string +--- @param init? integer +--- @return integer|vim.lpeg.Capture|nil +--- @see vim.lpeg.match() +function vim.re.match(subject, pattern, init) end + +--- Updates the pre-defined character classes to the current locale. +function vim.re.updatelocale() end -- cgit From e5ff71fbbfea0431826a82a6de24656d93651ec3 Mon Sep 17 00:00:00 2001 From: altermo Date: Sun, 14 Jan 2024 12:10:31 +0100 Subject: docs(builtin): overload functions with union return types --- runtime/lua/vim/_meta/vimfn.lua | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index f044871601..fd9b68a6f3 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -1843,7 +1843,13 @@ function vim.fn.exp(expr) end --- --- @param string string --- @param nosuf? boolean ---- @param list? any +--- @param list? nil|false +--- @return string +function vim.fn.expand(string, nosuf, list) end + +--- @param string string +--- @param nosuf boolean +--- @param list true|number|string|table --- @return string|string[] function vim.fn.expand(string, nosuf, list) end @@ -3138,7 +3144,12 @@ function vim.fn.getjumplist(winnr, tabnr) end --- |getbufoneline()| --- --- @param lnum integer ---- @param end_? any +--- @param end_? nil|false +--- @return string +function vim.fn.getline(lnum, end_) end + +--- @param lnum integer +--- @param end_ true|number|string|table --- @return string|string[] function vim.fn.getline(lnum, end_) end @@ -3436,7 +3447,12 @@ function vim.fn.getqflist(what) end --- If {regname} is not specified, |v:register| is used. --- --- @param regname? string ---- @param list? any +--- @param list? nil|false +--- @return string +function vim.fn.getreg(regname, list) end + +--- @param regname string +--- @param list true|number|string|table --- @return string|string[] function vim.fn.getreg(regname, list) end @@ -5067,7 +5083,14 @@ function vim.fn.map(expr1, expr2) end --- @param name string --- @param mode? string --- @param abbr? boolean ---- @param dict? boolean +--- @param dict? false +--- @return string +function vim.fn.maparg(name, mode, abbr, dict) end + +--- @param name string +--- @param mode string +--- @param abbr boolean +--- @param dict true --- @return string|table function vim.fn.maparg(name, mode, abbr, dict) end @@ -9317,7 +9340,12 @@ function vim.fn.strwidth(string) end --- A line break is included as a newline character. --- --- @param nr integer ---- @param list? integer +--- @param list? nil +--- @return string +function vim.fn.submatch(nr, list) end + +--- @param nr integer +--- @param list integer --- @return string|string[] function vim.fn.submatch(nr, list) end -- cgit From 4d91604c8868b7afaf429cc16b72192ce89ea698 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Sun, 14 Jan 2024 22:37:07 -0500 Subject: docs: add lua typing for `vim.NIL` --- runtime/lua/vim/_meta/builtin.lua | 9 ++++++++- runtime/lua/vim/_meta/vvars.lua | 2 +- 2 files changed, 9 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index eeba356672..dd849e5247 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -1,7 +1,8 @@ ---@meta - -- luacheck: no unused args +error('Cannot require a meta file') + ---@defgroup vim.builtin --- ---@brief 
help
@@ -62,6 +63,12 @@
 ---
 ---
+---@class vim.NIL + +---@type vim.NIL +---@nodoc +vim.NIL = ... + --- Returns true if the code is executing as part of a "fast" event handler, --- where most of the API is disabled. These are low-level events (e.g. --- |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input. diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index ca87fb9d15..958b4a7ccd 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -427,7 +427,7 @@ vim.v.msgpack_types = ... --- In some places `v:null` can be used for a List, Dict, etc. --- that is not set. That is slightly different than an empty --- List, Dict, etc. ---- @type any +--- @type vim.NIL vim.v.null = ... --- Maximum value of a number. -- cgit From fa836cb98b54dd170db485529cbeddb43c307ee1 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Sat, 6 Jan 2024 08:59:50 -0500 Subject: docs(vvars): fix wrong lua types in vim.v variables - cmdarg: string[] -> string - shell_error: string -> int - stderr: string -> int - Add types for: cmdbang, errors, exception, false, true --- runtime/lua/vim/_meta/vvars.lua | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua index 958b4a7ccd..ee6d8ddf35 100644 --- a/runtime/lua/vim/_meta/vvars.lua +++ b/runtime/lua/vim/_meta/vvars.lua @@ -34,14 +34,14 @@ vim.v.charconvert_to = ... --- leading space to make it possible to append this variable --- directly after the read/write command. Note: "+cmd" isn't --- included here, because it will be executed anyway. ---- @type string[] +--- @type string vim.v.cmdarg = ... --- Set like v:cmdarg for a file read/write command. When a "!" --- was used the value is 1, otherwise it is 0. Note that this --- can only be used in autocommands. For user commands `` --- can be used. ---- @type any +--- @type integer vim.v.cmdbang = ... --- The current locale setting for collation order of the runtime @@ -141,7 +141,7 @@ vim.v.errmsg = ... --- --- If v:errors is set to anything but a list it is made an empty --- list by the assert function. ---- @type any +--- @type string[] vim.v.errors = ... --- Dictionary of event data for the current `autocommand`. Valid @@ -210,7 +210,7 @@ vim.v.event = ... --- ``` --- --- Output: "caught oops". ---- @type any +--- @type string vim.v.exception = ... --- Exit code, or `v:null` before invoking the `VimLeavePre` @@ -228,7 +228,7 @@ vim.v.exiting = ... --- as a String (e.g. in `expr5` with string concatenation --- operator) and to zero when used as a Number (e.g. in `expr5` --- or `expr7` when used with numeric operators). Read-only. ---- @type any +--- @type boolean vim.v['false'] = ... --- What should happen after a `FileChangedShell` event was @@ -608,7 +608,7 @@ vim.v.servername = ... --- echo 'could not rename "foo" to "bar"!' --- endif --- ``` ---- @type string +--- @type integer vim.v.shell_error = ... --- Last given status message. @@ -624,7 +624,7 @@ vim.v.statusmsg = ... --- ```vim --- :call chansend(v:stderr, "error: toaster empty\n") --- ``` ---- @type string +--- @type integer vim.v.stderr = ... --- `SwapExists` autocommands can set this to the selected choice @@ -733,7 +733,7 @@ vim.v.throwpoint = ... --- as a String (e.g. in `expr5` with string concatenation --- operator) and to one when used as a Number (e.g. in `expr5` or --- `expr7` when used with numeric operators). Read-only. ---- @type any +--- @type boolean vim.v['true'] = ... --- Value of the current item of a `List` or `Dictionary`. Only -- cgit From 73e1942abe7a96d63ce3749af4187f2cdff87e69 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 16 Jan 2024 08:00:08 +0800 Subject: vim-patch:9.1.0009: Cannot easily get the list of matches (#27028) Problem: Cannot easily get the list of matches Solution: Add the matchstrlist() and matchbufline() Vim script functions (Yegappan Lakshmanan) closes: vim/vim#13766 Omit CHECK_LIST_MATERIALIZE(): it populates a List with numbers only, and there is a check for strings below. https://github.com/vim/vim/commit/f93b1c881a99fa847a1bafa71877d7e16f18e6ef vim-patch:eb3475df0d92 runtime(doc): Replace non-breaking space with normal space (vim/vim#13868) https://github.com/vim/vim/commit/eb3475df0d927a178789cf8e7fc4983932e1cdbe Co-authored-by: Yegappan Lakshmanan <4298407+yegappan@users.noreply.github.com> --- runtime/lua/vim/_meta/vimfn.lua | 85 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index fd9b68a6f3..01b4ef920b 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -5412,6 +5412,54 @@ function vim.fn.matchaddpos(group, pos, priority, id, dict) end --- @return any function vim.fn.matcharg(nr) end +--- Returns the |List| of matches in lines from {lnum} to {end} in +--- buffer {buf} where {pat} matches. +--- +--- {lnum} and {end} can either be a line number or the string "$" +--- to refer to the last line in {buf}. +--- +--- The {dict} argument supports following items: +--- submatches include submatch information (|/\(|) +--- +--- For each match, a |Dict| with the following items is returned: +--- byteidx starting byte index of the match +--- lnum line number where there is a match +--- text matched string +--- Note that there can be multiple matches in a single line. +--- +--- This function works only for loaded buffers. First call +--- |bufload()| if needed. +--- +--- When {buf} is not a valid buffer, the buffer is not loaded or +--- {lnum} or {end} is not valid then an error is given and an +--- empty |List| is returned. +--- +--- Examples: >vim +--- " Assuming line 3 in buffer 5 contains "a" +--- :echo matchbufline(5, '\<\k\+\>', 3, 3) +--- [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] +--- " Assuming line 4 in buffer 10 contains "tik tok" +--- :echo matchbufline(10, '\<\k\+\>', 1, 4) +--- [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] +--- < +--- If {submatch} is present and is v:true, then submatches like +--- "\1", "\2", etc. are also returned. Example: >vim +--- " Assuming line 2 in buffer 2 contains "acd" +--- :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 +--- \ {'submatches': v:true}) +--- [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +--- vim +--- :echo matchstrlist(['tik tok'], '\<\k\+\>') +--- [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] +--- :echo matchstrlist(['a', 'b'], '\<\k\+\>') +--- [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] +--- < +--- If "submatches" is present and is v:true, then submatches like +--- "\1", "\2", etc. are also returned. Example: >vim +--- :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', +--- \ #{submatches: v:true}) +--- [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +--- vim --- echo matchstrpos("testing", "ing") @@ -5612,7 +5695,7 @@ function vim.fn.matchstrpos(expr, pat, start, count) end --- it returns the maximum of all values in the Dictionary. --- If {expr} is neither a List nor a Dictionary, or one of the --- items in {expr} cannot be used as a Number this results in ---- an error. An empty |List| or |Dictionary| results in zero. +--- an error. An empty |List| or |Dictionary| results in zero. --- --- @param expr any --- @return any -- cgit From 46a7c1b3193d1f4ba09cd66ce03a1e2340d324a7 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 16 Jan 2024 11:30:35 +0800 Subject: vim-patch:partial:9.1.0027: Vim is missing a foreach() func (#27037) Problem: Vim is missing a foreach() func Solution: Implement foreach({expr1}, {expr2}) function, which applies {expr2} for each item in {expr1} without changing it (Ernie Rael) closes: vim/vim#12166 https://github.com/vim/vim/commit/e79e2077607e8f829ba823308c91104a795736ba Partial port as this doesn't handle non-materialized range() lists. vim-patch:c92b8bed1fa6 runtime(help): delete duplicate help tag E741 (vim/vim#13861) https://github.com/vim/vim/commit/c92b8bed1fa632569c8358feb3b72dd6a0844ef7 Co-authored-by: Ernie Rael --- runtime/lua/vim/_meta/vimfn.lua | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 01b4ef920b..59497f96e9 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -2308,6 +2308,45 @@ function vim.fn.foldtext() end --- @return string function vim.fn.foldtextresult(lnum) end +--- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. +--- For each item in {expr1} execute {expr2}. {expr1} is not +--- modified; its values may be, as with |:lockvar| 1. |E741| +--- See |map()| and |filter()| to modify {expr1}. +--- +--- {expr2} must be a |string| or |Funcref|. +--- +--- If {expr2} is a |string|, inside {expr2} |v:val| has the value +--- of the current item. For a |Dictionary| |v:key| has the key +--- of the current item and for a |List| |v:key| has the index of +--- the current item. For a |Blob| |v:key| has the index of the +--- current byte. For a |String| |v:key| has the index of the +--- current character. +--- Examples: > +--- call foreach(mylist, 'let used[v:val] = v:true') +--- Date: Tue, 16 Jan 2024 12:07:35 +0800 Subject: docs(builtin): remove signatures of undocumented functions (#27039) Having an empty signature causes an empty line in generated docs, so remove it. Also change ">" to ">vim" in foreach() docs. --- runtime/lua/vim/_meta/vimfn.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 59497f96e9..50f6e4da52 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -2321,7 +2321,7 @@ function vim.fn.foldtextresult(lnum) end --- the current item. For a |Blob| |v:key| has the index of the --- current byte. For a |String| |v:key| has the index of the --- current character. ---- Examples: > +--- Examples: >vim --- call foreach(mylist, 'let used[v:val] = v:true') --- Date: Sun, 7 Jan 2024 10:08:51 +0100 Subject: docs(column): 'statuscolumn' redraw interaction with 'relativenumber' --- runtime/lua/vim/_meta/options.lua | 3 +++ 1 file changed, 3 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 7ad720b6b2..b598b2c99a 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6373,6 +6373,9 @@ vim.go.sol = vim.go.startofline --- when drawing the actual buffer line, and positive when --- drawing the wrapped part of a buffer line. --- +--- When using `v:relnum`, keep in mind that cursor movement by itself will +--- not cause the 'statuscolumn' to update unless `'relativenumber'` is set. +--- --- NOTE: The %@ click execute function item is supported as well but the --- specified function will be the same for each row in the same column. --- It cannot be switched out through a dynamic 'statuscolumn' format, the -- cgit From b3e5587b7f1cd6206240aea38740d2205c10ae34 Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Wed, 17 Jan 2024 07:01:39 +0100 Subject: docs: various fixes (#26929) Co-authored-by: Patrick Bollinger Co-authored-by: vilo1839 <139687192+vilo1839@users.noreply.github.com> --- runtime/lua/vim/_meta/options.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index b598b2c99a..8c550fccdb 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6362,7 +6362,7 @@ vim.go.sol = vim.go.startofline --- The 'statuscolumn' width follows that of the default columns and --- adapts to the `'numberwidth'`, `'signcolumn'` and `'foldcolumn'` option --- values (regardless of whether the sign and fold items are present). ---- Aditionally, the 'statuscolumn' grows with the size of the evaluated +--- Additionally, the 'statuscolumn' grows with the size of the evaluated --- format string, up to a point (following the maximum size of the default --- fold, sign and number columns). Shrinking only happens when the number --- of lines in a buffer changes, or the 'statuscolumn' option is set. -- cgit From 780dd88b68b7a4d97c8b7ec6a8d33ab523ab04dd Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Thu, 18 Jan 2024 07:14:12 +0800 Subject: vim-patch:9.1.0039: too vague errors for 'listchars'/'fillchars' (#27070) Problem: too vague errors for 'listchars'/'fillchars' Solution: Include the field name in error message. (zeertzjq) related: #27050 closes: vim/vim#13877 https://github.com/vim/vim/commit/6a8d2e1634f8f0d7463a2786dbcbe0f38dd287a7 Co-authored-by: Cole Frankenhoff --- runtime/lua/vim/_meta/options.lua | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 8c550fccdb..c9e2e302dc 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -2197,7 +2197,7 @@ vim.bo.ft = vim.bo.filetype --- Characters to fill the statuslines, vertical separators and special --- lines in the window. --- It is a comma-separated list of items. Each item has a name, a colon ---- and the value of that item: +--- and the value of that item: `E1511` --- --- item default Used for ~ --- stl ' ' statusline of the current window @@ -2238,7 +2238,7 @@ vim.bo.ft = vim.bo.filetype --- --- For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items --- single-byte and multibyte characters are supported. But double-width ---- characters are not supported. +--- characters are not supported. `E1512` --- --- The highlighting used for these items: --- item highlight group ~ @@ -3829,7 +3829,7 @@ vim.o.list = false vim.wo.list = vim.o.list --- Strings to use in 'list' mode and for the `:list` command. It is a ---- comma-separated list of string settings. +--- comma-separated list of string settings. *E1511* --- --- *lcs-eol* --- eol:c Character to show at the end of each line. When @@ -3921,7 +3921,7 @@ vim.wo.list = vim.o.list --- omitted. --- --- The characters ':' and ',' should not be used. UTF-8 characters can ---- be used. All characters must be single width. +--- be used. All characters must be single width. *E1512* --- --- Each character can be specified as hex: --- -- cgit From 2645c9d576e430e62b60d1902d4a6b887e46a670 Mon Sep 17 00:00:00 2001 From: Luuk van Baal Date: Wed, 17 Jan 2024 15:55:00 +0100 Subject: docs(extmarks): add undocumented "details" array fields --- runtime/lua/vim/_meta/api.lua | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 3f06d4fd43..f773ddd75c 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -323,8 +323,8 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @return integer[] function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end ---- Gets `extmarks` (including `signs`) in "traversal order" from a `charwise` ---- region defined by buffer positions (inclusive, 0-indexed `api-indexing`). +--- Gets `extmarks` in "traversal order" from a `charwise` region defined by +--- buffer positions (inclusive, 0-indexed `api-indexing`). --- Region can be given as (row,col) tuples, or valid extmark ids (whose --- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) --- respectively, thus the following are equivalent: @@ -339,6 +339,9 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Note: when using extmark ranges (marks with a end_row/end_col position) --- the `overlap` option might be useful. Otherwise only the start position of --- an extmark will be considered. +--- Note: legacy signs placed through the `:sign` commands are implemented as +--- extmarks and will show up here. Their details array will contain a +--- `sign_name` field. --- Example: --- --- ```lua @@ -567,7 +570,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- text around the mark was deleted and then restored by --- undo. Defaults to true. --- • invalidate : boolean that indicates whether to hide the ---- extmark if the entirety of its range is deleted. If +--- extmark if the entirety of its range is deleted. For +--- hidden marks, an "invalid" key is added to the "details" +--- array of `nvim_buf_get_extmarks()` and family. If --- "undo_restore" is false, the extmark is deleted instead. --- • priority: a priority value for the highlight group or sign --- attribute. For example treesitter highlighting uses a -- cgit From 646fdf1073433e2bdeec3433f6cbdf8f4be37098 Mon Sep 17 00:00:00 2001 From: glepnir Date: Wed, 17 Jan 2024 20:14:26 +0800 Subject: refactor(api): use hl id directly in nvim_buf_set_extmark --- runtime/lua/vim/_meta/api_keysets.lua | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index bb1031b2fa..377060256a 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -246,7 +246,7 @@ error('Cannot require a meta file') --- @field end_line? integer --- @field end_row? integer --- @field end_col? integer ---- @field hl_group? any +--- @field hl_group? integer --- @field virt_text? any[] --- @field virt_text_pos? string --- @field virt_text_win_col? integer @@ -264,10 +264,10 @@ error('Cannot require a meta file') --- @field virt_lines_leftcol? boolean --- @field strict? boolean --- @field sign_text? string ---- @field sign_hl_group? any ---- @field number_hl_group? any ---- @field line_hl_group? any ---- @field cursorline_hl_group? any +--- @field sign_hl_group? integer +--- @field number_hl_group? integer +--- @field line_hl_group? integer +--- @field cursorline_hl_group? integer --- @field conceal? string --- @field spell? boolean --- @field ui_watched? boolean -- cgit From d66ed4ea468d411668713c3777ad3658f18badf3 Mon Sep 17 00:00:00 2001 From: bfredl Date: Mon, 22 Jan 2024 08:49:45 +0100 Subject: refactor(api): give "hl_group" more accurate _meta type These can either be number or string in lua, so we can specify this directly as "number|string". --- runtime/lua/vim/_meta/api_keysets.lua | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 377060256a..5ebedc977b 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -246,7 +246,7 @@ error('Cannot require a meta file') --- @field end_line? integer --- @field end_row? integer --- @field end_col? integer ---- @field hl_group? integer +--- @field hl_group? number|string --- @field virt_text? any[] --- @field virt_text_pos? string --- @field virt_text_win_col? integer @@ -264,10 +264,10 @@ error('Cannot require a meta file') --- @field virt_lines_leftcol? boolean --- @field strict? boolean --- @field sign_text? string ---- @field sign_hl_group? integer ---- @field number_hl_group? integer ---- @field line_hl_group? integer ---- @field cursorline_hl_group? integer +--- @field sign_hl_group? number|string +--- @field number_hl_group? number|string +--- @field line_hl_group? number|string +--- @field cursorline_hl_group? number|string --- @field conceal? string --- @field spell? boolean --- @field ui_watched? boolean -- cgit From 12d123959f56636473112d86ec5977ef993c58e5 Mon Sep 17 00:00:00 2001 From: Raphael Date: Mon, 22 Jan 2024 16:04:50 +0800 Subject: fix(eval): properly support checking v:lua function in exists() (#27124) --- runtime/lua/vim/_meta/vimfn.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 50f6e4da52..011bfb7c11 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -1709,6 +1709,7 @@ function vim.fn.exepath(expr) end --- echo exists("*strftime") --- echo exists("*s:MyFunc") --- echo exists("*MyFunc") +--- echo exists("*v:lua.Func") --- echo exists("bufcount") --- echo exists(":Make") --- echo exists("#CursorHold") -- cgit From 1233ac467de7504b277425988ef9be7f8d3a9626 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Mon, 22 Jan 2024 10:13:35 +0000 Subject: feat(fold): transparent foldtext 'foldtext' can be set to an empty string to disable and render the line with: - extmark highlight - syntax highlighting - search highlighting - no line wrapping - spelling - conceal - inline virtual text - respects `fillchars:fold` Currently normal virtual text is not displayed Co-authored-by: zeertzjq --- runtime/lua/vim/_meta/options.lua | 3 +++ 1 file changed, 3 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index c9e2e302dc..60339f57d8 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -2473,6 +2473,9 @@ vim.go.fdo = vim.go.foldopen --- It is not allowed to change text or jump to another window while --- evaluating 'foldtext' `textlock`. --- +--- When set to an empty string, foldtext is disabled, and the line +--- is displayed normally with highlighting and no line wrapping. +--- --- @type string vim.o.foldtext = "foldtext()" vim.o.fdt = vim.o.foldtext -- cgit From cb6320e13f9a4f13ec745ce0bc34203cfa7612d0 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Mon, 22 Jan 2024 22:54:45 +0800 Subject: docs(options): remove misleading sentence (#27129) Setting 'verbose' to 1 doesn't cause Nvim to produce messages. It adds more information to existing messages, which is documented above. --- runtime/lua/vim/_meta/options.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 60339f57d8..1a215b1715 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -7432,15 +7432,15 @@ vim.bo.vts = vim.bo.vartabstop --- Sets the verbosity level. Also set by `-V` and `:verbose`. --- ---- Tracing of options in Lua scripts is activated at level 1; Lua scripts ---- are not traced with verbose=0, for performance. +--- Tracing of assignments to options, mappings, etc. in Lua scripts is +--- enabled at level 1; Lua scripts are not traced when 'verbose' is 0, +--- for performance. --- --- If greater than or equal to a given level, Nvim produces the following --- messages: --- --- Level Messages ~ --- ---------------------------------------------------------------------- ---- 1 Lua assignments to options, mappings, etc. --- 2 When a file is ":source"'ed, or `shada` file is read or written. --- 3 UI info, terminal capabilities. --- 4 Shell commands. -- cgit From 8c044f0862f417a525eaf319471c286a5588d493 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Wed, 24 Jan 2024 18:13:39 +0800 Subject: fix(spell): always accept ':' as filename char in 'spellfile' (#27172) Follow-up to #25236 --- runtime/lua/vim/_meta/options.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 1a215b1715..83da61cc2b 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6135,7 +6135,7 @@ vim.bo.spc = vim.bo.spellcapcheck --- Name of the word list file where words are added for the `zg` and `zw` --- commands. It must end in ".{encoding}.add". You need to include the --- path, otherwise the file is placed in the current directory. ---- The path may include characters from 'isfname', space, comma and '@'. +--- The path may include characters from 'isfname', ' ', ',', '@' and ':'. --- *E765* --- It may also be a comma-separated list of names. A count before the --- `zg` and `zw` commands can be used to access each. This allows using -- cgit From 6ea6b3fee27d51607ca4a5ace46dbc38a4481bcb Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Wed, 24 Jan 2024 16:36:25 -0600 Subject: feat(ui): add support for OSC 8 hyperlinks (#27109) Extmarks can contain URLs which can then be drawn in any supporting UI. In the TUI, for example, URLs are "drawn" by emitting the OSC 8 control sequence to the TTY. On terminals which support the OSC 8 sequence this will create clickable hyperlinks. URLs are treated as inline highlights in the decoration subsystem, so are included in the `DecorSignHighlight` structure. However, unlike other inline highlights they use allocated memory which must be freed, so they set the `ext` flag in `DecorInline` so that their lifetimes are managed along with other allocated memory like virtual text. The decoration subsystem then adds the URLs as a new highlight attribute. The highlight subsystem maintains a set of unique URLs to avoid duplicating allocations for the same string. To attach a URL to an existing highlight attribute we call `hl_add_url` which finds the URL in the set (allocating and adding it if it does not exist) and sets the `url` highlight attribute to the index of the URL in the set (using an index helps keep the size of the `HlAttrs` struct small). This has the potential to lead to an increase in highlight attributes if a URL is used over a range that contains many different highlight attributes, because now each existing attribute must be combined with the URL. In practice, however, URLs typically span a range containing a single highlight (e.g. link text in Markdown), so this is likely just a pathological edge case. When a new highlight attribute is defined with a URL it is copied to all attached UIs with the `hl_attr_define` UI event. The TUI manages its own set of URLs (just like the highlight subsystem) to minimize allocations. The TUI keeps track of which URL is "active" for the cell it is printing. If no URL is active and a cell containing a URL is printed, the opening OSC 8 sequence is emitted and that URL becomes the actively tracked URL. If the cursor is moved while in the middle of a URL span, we emit the terminating OSC sequence to prevent the hyperlink from spanning multiple lines. This does not support nested hyperlinks, but that is a rare (and, frankly, bizarre) use case. If a valid use case for nested hyperlinks ever presents itself we can address that issue then. --- runtime/lua/vim/_meta/api.lua | 3 +++ runtime/lua/vim/_meta/api_keysets.lua | 2 ++ 2 files changed, 5 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index f773ddd75c..076aae7dbe 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -607,6 +607,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- drawn by a UI. When set, the UI will receive win_extmark --- events. Note: the mark is positioned by virt_text --- attributes. Can be used together with virt_text. +--- • url: A URL to associate with this extmark. In the TUI, the +--- OSC 8 control sequence is used to generate a clickable +--- hyperlink to this URL. --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 5ebedc977b..00d3ff5bb4 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -192,6 +192,7 @@ error('Cannot require a meta file') --- @field fg_indexed? boolean --- @field bg_indexed? boolean --- @field force? boolean +--- @field url? string --- @class vim.api.keyset.highlight_cterm --- @field bold? boolean @@ -272,6 +273,7 @@ error('Cannot require a meta file') --- @field spell? boolean --- @field ui_watched? boolean --- @field undo_restore? boolean +--- @field url? string --- @class vim.api.keyset.user_command --- @field addr? any -- cgit From 76a659eb773ca69d8b6a8f08e1a5c538dc03b8fd Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Thu, 25 Jan 2024 00:34:18 +0100 Subject: docs: various fixes (#27063) Co-authored-by: lmenou Co-authored-by: altermo <107814000+altermo@users.noreply.github.com> Co-authored-by: VanaIgr Co-authored-by: Gregory Anders --- runtime/lua/vim/_meta/vimfn.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 011bfb7c11..7f5860c3a3 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -9684,7 +9684,7 @@ function vim.fn.synIDtrans(synID) end --- --- @param lnum integer --- @param col integer ---- @return {[1]: integer, [2]: string, [3]: integer}[] +--- @return {[1]: integer, [2]: string, [3]: integer} function vim.fn.synconcealed(lnum, col) end --- Return a |List|, which is the stack of syntax items at the -- cgit From 226466a46941cd6b693f56b6eb7f4293d4066c8d Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 26 Jan 2024 11:04:54 +0800 Subject: vim-patch:9.1.0058: Cannot map Super Keys in GTK UI (#27204) Problem: Cannot map Super Keys in GTK UI (Casey Tucker) Solution: Enable Super Key mappings in GTK using (Casey Tucker) As a developer who works in both Mac and Linux using the same keyboard, it can be frustrating having to remember different key combinations or having to rely on system utilities to remap keys. This change allows `` `` `` `` etc. to be recognized by the `map` commands, along with the `` shifted variants. ```vimrc if has('gui_gtk') nnoremap u nnoremap vnoremap "+d vnoremap "+y cnoremap + inoremap "+gP nnoremap "+P vnoremap "-d"+P nnoremap :w inoremap :w nnoremap :q nnoremap :qa nnoremap :tabe nnoremap :vs#T nnoremap ggVG vnoremap ggVG inoremap ggVG nnoremap / nnoremap n nnoremap N vnoremap "+x endif ``` closes: vim/vim#12698 https://github.com/vim/vim/commit/92e90a1e102825aa9149262cacfc991264db05df Co-authored-by: Casey Tucker --- runtime/lua/vim/_meta/vimfn.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 7f5860c3a3..2280eec5c8 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -2777,7 +2777,7 @@ function vim.fn.getchar() end --- 32 mouse double click --- 64 mouse triple click --- 96 mouse quadruple click (== 32 + 64) ---- 128 command (Macintosh only) +--- 128 command (Mac) or super --- Only the modifiers that have not been included in the --- character itself are obtained. Thus Shift-a results in "A" --- without a modifier. Returns 0 if no modifiers are used. -- cgit From 28d1640dd6043f25cd3ae761dc9c4c8d374a8ce1 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 26 Jan 2024 11:38:19 +0000 Subject: feat: improve return type annotations for vim.api.* --- runtime/lua/vim/_meta/api.lua | 28 ++--- runtime/lua/vim/_meta/api_keysets_extra.lua | 167 ++++++++++++++++++++++++++++ 2 files changed, 181 insertions(+), 14 deletions(-) create mode 100644 runtime/lua/vim/_meta/api_keysets_extra.lua (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 076aae7dbe..f9fa364158 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -320,7 +320,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead --- of id, true if omitted ---- @return integer[] +--- @return vim.api.keyset.get_extmark_item function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by @@ -376,14 +376,14 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- if their start position is less than `start` --- • type: Filter marks by type: "highlight", "sign", --- "virt_text" and "virt_lines" ---- @return any[] +--- @return vim.api.keyset.get_extmark_item[] function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- Gets a list of buffer-local `mapping` definitions. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return table[] +--- @return vim.api.keyset.keymap[] function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. @@ -1153,7 +1153,7 @@ function vim.api.nvim_get_all_options_info() end --- • buffer: Buffer number or list of buffer numbers for buffer --- local autocommands `autocmd-buflocal`. Cannot be used with --- {pattern} ---- @return any[] +--- @return vim.api.keyset.get_autocmds.ret[] function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. @@ -1179,7 +1179,7 @@ function vim.api.nvim_get_color_by_name(name) end --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values --- (e.g. 65535). --- ---- @return table +--- @return table function vim.api.nvim_get_color_map() end --- Gets a map of global (non-buffer-local) Ex commands. @@ -1229,7 +1229,7 @@ function vim.api.nvim_get_current_win() end --- instead of effective definition `:hi-link`. --- • create: (boolean, default true) When highlight group --- doesn't exist create it. ---- @return table +--- @return vim.api.keyset.hl_info function vim.api.nvim_get_hl(ns_id, opts) end --- @deprecated @@ -1264,7 +1264,7 @@ function vim.api.nvim_get_hl_ns(opts) end --- Gets a list of global (non-buffer-local) `mapping` definitions. --- --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return table[] +--- @return vim.api.keyset.keymap[] function vim.api.nvim_get_keymap(mode) end --- Returns a `(row, col, buffer, buffername)` tuple representing the position @@ -1274,18 +1274,18 @@ function vim.api.nvim_get_keymap(mode) end --- --- @param name string Mark name --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. ---- @return any[] +--- @return vim.api.keyset.get_mark function vim.api.nvim_get_mark(name, opts) end --- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for --- input. --- ---- @return table +--- @return vim.api.keyset.get_mode function vim.api.nvim_get_mode() end --- Gets existing, non-anonymous `namespace`s. --- ---- @return table +--- @return table function vim.api.nvim_get_namespaces() end --- @deprecated @@ -1295,7 +1295,7 @@ function vim.api.nvim_get_option(name) end --- @deprecated --- @param name string ---- @return table +--- @return vim.api.keyset.get_option_info function vim.api.nvim_get_option_info(name) end --- Gets the option information for one option from arbitrary buffer or window @@ -1325,7 +1325,7 @@ function vim.api.nvim_get_option_info(name) end --- • win: `window-ID`. Used for getting window local options. --- • buf: Buffer number. Used for getting buffer local options. --- Implies {scope} is "local". ---- @return table +--- @return vim.api.keyset.get_option_info function vim.api.nvim_get_option_info2(name, opts) end --- Gets the value of an option. The behavior of this function matches that of @@ -1637,7 +1637,7 @@ function vim.api.nvim_out_write(str) end --- --- @param str string Command line string to parse. Cannot contain "\n". --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. ---- @return table +--- @return vim.api.keyset.parse_cmd function vim.api.nvim_parse_cmd(str, opts) end --- Parse a Vimscript expression. @@ -1985,7 +1985,7 @@ function vim.api.nvim_win_get_buf(window) end --- `relative` is empty for normal windows. --- --- @param window integer Window handle, or 0 for current window ---- @return table +--- @return vim.api.keyset.float_config function vim.api.nvim_win_get_config(window) end --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua new file mode 100644 index 0000000000..8e34ee534c --- /dev/null +++ b/runtime/lua/vim/_meta/api_keysets_extra.lua @@ -0,0 +1,167 @@ +--- @meta _ +error('Cannot require a meta file') + +--- Extra types we can't generate keysets for + +--- @class vim.api.keyset.extmark_details +--- @field ns_id integer +--- @field right_gravity boolean +--- +--- @field end_row? integer +--- @field end_col? integer +--- @field end_right_gravity? integer +--- +--- @field priority? integer +--- +--- @field undo_restore? false +--- @field invalidate? true +--- @field invalid? true +--- +--- @field hl_group? string +--- @field hl_eol? boolean +--- +--- @field conceal? boolean +--- @field spell? boolean +--- @field ui_watched? boolean +--- @field url? boolean +--- @field hl_mode? string +--- +--- @field virt_text? {[1]: string, [2]: string}[] +--- @field virt_text_hide? boolean +--- @field virt_text_repeat_linebreak? boolean +--- @field virt_text_win_col? integer +--- @field virt_text_pos? string +--- +--- @field virt_lines? {[1]: string, [2]: string}[][] +--- @field virt_lines_above? boolean +--- @field virt_lines_leftcol? boolean +--- +--- @field sign_text? string +--- @field sign_name? string +--- @field sign_hl_group? string +--- @field number_hl_group? string +--- @field line_hl_group? string +--- @field cursorline_hl_group? string + +--- @class vim.api.keyset.get_extmark_item +--- @field [1] integer row +--- @field [2] integer col +--- @field [3] vim.api.keyset.extmark_details? + +--- @class vim.api.keyset.get_mark +--- @field [1] integer row +--- @field [2] integer col +--- @field [3] integer buffer +--- @field [4] string buffername + +--- @class vim.api.keyset.get_autocmds.ret +--- @field id? integer +--- @field group? integer +--- @field group_name? integer +--- @field desc? string +--- @field event? string +--- @field command? string +--- @field callback? function +--- @field once? boolean +--- @field pattern? string +--- @field buflocal? boolean +--- @field buffer? integer + +--- @class vim.api.keyset.command_info +--- @field name string +--- @field definition string +--- @field script_id integer +--- @field bang boolean +--- @field bar boolean +--- @field register boolean +--- @field keepscript boolean +--- @field preview boolean +--- @field nargs string +--- @field complete? string +--- @field complete_arg? string +--- @field count? string +--- @field range? string +--- @field addr? string + +--- @class vim.api.keyset.hl_info.base +--- @field reverse? true +--- @field bold? true +--- @field italic? true +--- @field underline? true +--- @field undercurl? true +--- @field underdouble? true +--- @field underdotted? true +--- @field underdashed? true +--- @field standout? true +--- @field strikethrough? true +--- @field altfont? true +--- @field nocombine? true + +--- @class vim.api.keyset.hl_info.cterm : vim.api.keyset.hl_info.base +--- @field ctermfg? integer +--- @field ctermbg? integer +--- @field foreground? integer +--- @field background? integer + +--- @class vim.api.keyset.hl_info : vim.api.keyset.hl_info.base +--- @field fg? integer +--- @field bg? integer +--- @field sp? integer +--- @field default? true +--- @field link? string +--- @field blend? integer +--- @field cterm? vim.api.keyset.hl_info.cterm + +--- @class vim.api.keyset.get_mode +--- @field blocking boolean +--- @field mode string + +--- @class vim.api.keyset.get_option_info +--- @field name string +--- @field shortname string +--- @field scope 'buf'|'win'|'global' +--- @field global_local boolean +--- @field commalist boolean +--- @field flaglist boolean +--- @field was_set boolean +--- @field last_set_id integer +--- @field last_set_linenr integer +--- @field last_set_chan integer +--- @field type 'string'|'boolean'|'number' +--- @field default string|boolean|integer +--- @field allow_duplicates boolean + +--- @class vim.api.keyset.parse_cmd.mods +--- @field filter { force: boolean, pattern: string } +--- @field silent boolean +--- @field emsg_silent boolean +--- @field unsilent boolean +--- @field sandbox boolean +--- @field noautocmd boolean +--- @field tab integer +--- @field verbose integer +--- @field browse boolean +--- @field confirm boolean +--- @field hide boolean +--- @field keepalt boolean +--- @field keepjumps boolean +--- @field keepmarks boolean +--- @field keeppatterns boolean +--- @field lockmarks boolean +--- @field noswapfile boolean +--- @field vertical boolean +--- @field horizontal boolean +--- @field split ''|'botright'|'topleft'|'belowright'|'aboveleft' + +--- @class vim.api.keyset.parse_cmd +--- @field addr 'line'|'arg'|'buf'|'load'|'win'|'tab'|'qf'|'none'|'?' +--- @field args string[] +--- @field bang boolean +--- @field cmd string +--- @field magic {bar: boolean, file: boolean} +--- @field mods vim.api.keyset.parse_cmd.mods +--- @field nargs '0'|'1'|'?'|'+'|'*' +--- @field nextcmd string +--- @field range? integer[] +--- @field count? integer +--- @field reg? string -- cgit From d85f180f26c0570c2510c899a0bf0023ec55a692 Mon Sep 17 00:00:00 2001 From: Sean Dewar Date: Tue, 15 Aug 2023 19:38:52 +0100 Subject: vim-patch:9.1.0049: Make "[Command Line]" a special buffer name Problem: E95 is possible if a buffer called "[Command Line]" already exists when opening the cmdwin. This can also happen if the cmdwin's buffer could not be deleted when closing. Solution: Un-name the cmdwin buffer, and give it a special name instead, similar to what's done for quickfix buffers and for unnamed prompt and scratch buffers. As a result, BufFilePre/Post are no longer fired when opening the cmdwin. Add a "command" key to the dictionary returned by getbufinfo() to differentiate the cmdwin buffer instead. (Sean Dewar) Cherry-pick test_normal changes from v9.0.0954. https://github.com/vim/vim/commit/1fb41032060df09ca2640dc49541f11062f6dfaa --- runtime/lua/vim/_meta/vimfn.lua | 2 ++ 1 file changed, 2 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 2280eec5c8..acf3750500 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -2562,6 +2562,8 @@ function vim.fn.getbufinfo(buf) end --- bufnr Buffer number. --- changed TRUE if the buffer is modified. --- changedtick Number of changes made to the buffer. +--- command TRUE if the buffer belongs to the +--- command-line window |cmdwin|. --- hidden TRUE if the buffer is hidden. --- lastused Timestamp in seconds, like --- |localtime()|, when the buffer was -- cgit From 15e77a56b711102fdc123e15b3f37d49bc0b1df1 Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Sun, 28 Jan 2024 21:13:58 -0600 Subject: feat(extmarks): subpriorities (relative to declaration order) (#27131) The "priority" field of extmarks can be used to set priorities of extmarks which dictates which highlight group a range will actually have when there are multiple extmarks applied. However, when multiple extmarks have the same priority, the only way to enforce an actual priority is through the order in which the extmarks are set. It is not always possible or desirable to set extmarks in a specific order, however, so we add a new "subpriority" field that explicitly enforces the ordering of extmarks that have the same priority. For now this will be used only to enforce priority of treesitter highlights. A single node in a treesitter tree may match multiple captures, in which case that node will have multiple extmarks set. The order in which captures are returned from the treesitter API is not _necessarily_ in the same order they are defined in a query file, so we use the new subpriority field to force that ordering. For now subpriorites are not documented and are not meant to be used by external code, and it only applies to ephemeral extmarks. We indicate the "private" nature of subpriorities by prefixing the field name with an "_". --- runtime/lua/vim/_meta/api_keysets.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 00d3ff5bb4..c9ef4e9b4f 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -274,6 +274,7 @@ error('Cannot require a meta file') --- @field ui_watched? boolean --- @field undo_restore? boolean --- @field url? string +--- @field _subpriority? integer --- @class vim.api.keyset.user_command --- @field addr? any -- cgit From ca9f6f56949d66f0f6467fa64b215f861fe0a3bf Mon Sep 17 00:00:00 2001 From: Will Hopkins Date: Sun, 28 Jan 2024 23:18:33 -0800 Subject: feat(api): add nvim_tabpage_set_win (#27222) Allows setting the current window of a non-current tabpage without switching tabpages. --- runtime/lua/vim/_meta/api.lua | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index f9fa364158..bedc218626 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1952,6 +1952,12 @@ function vim.api.nvim_tabpage_list_wins(tabpage) end --- @param value any Variable value function vim.api.nvim_tabpage_set_var(tabpage, name, value) end +--- Sets the current window in a tabpage +--- +--- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param win integer Window handle, must already belong to {tabpage} +function vim.api.nvim_tabpage_set_win(tabpage, win) end + --- Calls a function with window as temporary current window. --- --- @param window integer Window handle, or 0 for current window -- cgit From 6bba4becedaea5a330c0c9d9427fb495e8092dac Mon Sep 17 00:00:00 2001 From: Will Hopkins Date: Wed, 31 Jan 2024 19:43:35 -0800 Subject: feat(api): make nvim_open_win support non-floating windows (#25550) Adds support to `nvim_open_win` and `nvim_win_set_config` for creating and manipulating split (non-floating) windows. --- runtime/lua/vim/_meta/api.lua | 39 +++++++++++++++++++++++++++-------- runtime/lua/vim/_meta/api_keysets.lua | 2 ++ 2 files changed, 32 insertions(+), 9 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index bedc218626..77a29cb4c1 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1483,15 +1483,24 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- @return integer function vim.api.nvim_open_term(buffer, opts) end ---- Open a new window. ---- Currently this is used to open floating and external windows. Floats are ---- windows that are drawn above the split layout, at some anchor position in ---- some other window. Floats can be drawn internally or by external GUI with ---- the `ui-multigrid` extension. External windows are only supported with ---- multigrid GUIs, and are displayed as separate top-level windows. +--- Opens a new split window, or a floating window if `relative` is specified, +--- or an external window (managed by the UI) if `external` is specified. +--- Floats are windows that are drawn above the split layout, at some anchor +--- position in some other window. Floats can be drawn internally or by +--- external GUI with the `ui-multigrid` extension. External windows are only +--- supported with multigrid GUIs, and are displayed as separate top-level +--- windows. --- For a general overview of floats, see `api-floatwin`. ---- Exactly one of `external` and `relative` must be specified. The `width` ---- and `height` of the new window must be specified. +--- The `width` and `height` of the new window must be specified when opening +--- a floating window, but are optional for normal windows. +--- If `relative` and `external` are omitted, a normal "split" window is +--- created. The `win` property determines which window will be split. If no +--- `win` is provided or `win == 0`, a window will be created adjacent to the +--- current window. If -1 is provided, a top-level split will be created. +--- `vertical` and `split` are only valid for normal windows, and are used to +--- control split direction. For `vertical`, the exact direction is determined +--- by `'splitright'` and `'splitbelow'`. Split windows cannot have +--- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. --- With relative=editor (row=0,col=0) refers to the top-left corner of the --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right --- corner. Fractional values are allowed, but the builtin implementation @@ -1515,6 +1524,15 @@ function vim.api.nvim_open_term(buffer, opts) end --- {relative='win', width=12, height=3, bufpos={100,10}}) --- ``` --- +--- Example (Lua): vertical split left of the current window +--- +--- ```lua +--- vim.api.nvim_open_win(0, false, { +--- split = 'left', +--- win = 0 +--- }) +--- ``` +--- --- @param buffer integer Buffer to display, or 0 for current buffer --- @param enter boolean Enter the window (make it the current window) --- @param config vim.api.keyset.float_config Map defining the window configuration. Keys: @@ -1526,7 +1544,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- • "cursor" Cursor position in current window. --- • "mouse" Mouse position --- ---- • win: `window-ID` for relative="win". +--- • win: `window-ID` window to split, or relative window when +--- creating a float (relative="win"). --- • anchor: Decides which corner of the float to place at --- (row,col): --- • "NW" northwest (default) @@ -1623,6 +1642,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- • fixed: If true when anchor is NW or SW, the float window --- would be kept fixed even if the window would be truncated. --- • hide: If true the floating window will be hidden. +--- • vertical: Split vertically `:vertical`. +--- • split: Split direction: "left", "right", "above", "below". --- @return integer function vim.api.nvim_open_win(buffer, enter, config) end diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index c9ef4e9b4f..1b6c6811a2 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -118,10 +118,12 @@ error('Cannot require a meta file') --- @field height? integer --- @field anchor? string --- @field relative? string +--- @field split? string --- @field win? integer --- @field bufpos? any[] --- @field external? boolean --- @field focusable? boolean +--- @field vertical? boolean --- @field zindex? integer --- @field border? any --- @field title? any -- cgit From b162adbb7ca4f980e938a4a06a49218a9ed496cf Mon Sep 17 00:00:00 2001 From: nikolightsaber <103886134+nikolightsaber@users.noreply.github.com> Date: Thu, 8 Feb 2024 11:59:31 +0100 Subject: feat(api): pass 0 to nvim_get_chan_info for current channel (#27321) Getting current channel info was kind of annoying via RPC. Two functions had to be called: 1. `nvim_get_api_info` which returns `[channel_id, meta_data]`. - This results in `channel_id = api.nvim_get_api_info()[0]`. - Here the meta_data is sent but never used. 2. Finally call `nvim_get_chan_info(channel_id)`. This commit reduces the need for `nvim_get_api_info` as passing 0 returns current channel info. --- runtime/lua/vim/_meta/api.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 77a29cb4c1..8b29727196 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1158,7 +1158,7 @@ function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. --- ---- @param chan integer +--- @param chan integer channel_id, or 0 for current channel --- @return table function vim.api.nvim_get_chan_info(chan) end -- cgit From 44ec4b5b18d1ba856dc3305d8dfb0e8d9507dd50 Mon Sep 17 00:00:00 2001 From: Will Hopkins Date: Fri, 9 Feb 2024 08:17:10 -0800 Subject: refactor: rename FloatConfig to WinConfig #27397 `FloatConfig` is no longer used only for floats, so the name is counterintuitive. Followup to #25550 --- runtime/lua/vim/_meta/api.lua | 4 +-- runtime/lua/vim/_meta/api_keysets.lua | 48 +++++++++++++++++------------------ 2 files changed, 26 insertions(+), 26 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 8b29727196..f46ab8023f 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1535,7 +1535,7 @@ function vim.api.nvim_open_term(buffer, opts) end --- --- @param buffer integer Buffer to display, or 0 for current buffer --- @param enter boolean Enter the window (make it the current window) ---- @param config vim.api.keyset.float_config Map defining the window configuration. Keys: +--- @param config vim.api.keyset.win_config Map defining the window configuration. Keys: --- • relative: Sets the window layout to "floating", placed at --- (row,col) coordinates relative to: --- • "editor" The global editor grid @@ -2093,7 +2093,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- changed. `row`/`col` and `relative` must be reconfigured together. --- --- @param window integer Window handle, or 0 for current window ---- @param config vim.api.keyset.float_config Map defining the window configuration, see `nvim_open_win()` +--- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()` function vim.api.nvim_win_set_config(window, config) end --- Sets the (1,0)-indexed cursor position in the window. `api-indexing` This diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 1b6c6811a2..0442a89e3f 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -111,30 +111,6 @@ error('Cannot require a meta file') --- @class vim.api.keyset.exec_opts --- @field output? boolean ---- @class vim.api.keyset.float_config ---- @field row? number ---- @field col? number ---- @field width? integer ---- @field height? integer ---- @field anchor? string ---- @field relative? string ---- @field split? string ---- @field win? integer ---- @field bufpos? any[] ---- @field external? boolean ---- @field focusable? boolean ---- @field vertical? boolean ---- @field zindex? integer ---- @field border? any ---- @field title? any ---- @field title_pos? string ---- @field footer? any ---- @field footer_pos? string ---- @field style? string ---- @field noautocmd? boolean ---- @field fixed? boolean ---- @field hide? boolean - --- @class vim.api.keyset.get_autocmds --- @field event? any --- @field group? any @@ -292,6 +268,30 @@ error('Cannot require a meta file') --- @field range? any --- @field register? boolean +--- @class vim.api.keyset.win_config +--- @field row? number +--- @field col? number +--- @field width? integer +--- @field height? integer +--- @field anchor? string +--- @field relative? string +--- @field split? string +--- @field win? integer +--- @field bufpos? any[] +--- @field external? boolean +--- @field focusable? boolean +--- @field vertical? boolean +--- @field zindex? integer +--- @field border? any +--- @field title? any +--- @field title_pos? string +--- @field footer? any +--- @field footer_pos? string +--- @field style? string +--- @field noautocmd? boolean +--- @field fixed? boolean +--- @field hide? boolean + --- @class vim.api.keyset.win_text_height --- @field start_row? integer --- @field end_row? integer -- cgit From 170c890dca8f160bdcd41e4fdc6bf15ee0bdba49 Mon Sep 17 00:00:00 2001 From: Trevor Arjeski Date: Sun, 11 Feb 2024 02:39:39 +0300 Subject: feat(shortmess): "q" flag fully hides recording message (#27415) When "q" is set in 'shortmess' it now fully hides the "recording @a" message when you are recording a macro instead of just shortening to "recording". This removes duplication when using reg_recording() in the statusline. Related #19193 --- runtime/lua/vim/_meta/options.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 83da61cc2b..835bd95a3a 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -5797,7 +5797,7 @@ vim.bo.sw = vim.bo.shiftwidth --- match", "Pattern not found", "Back at original", etc. --- C don't give messages while scanning for ins-completion *shm-C* --- items, for instance "scanning tags" ---- q use "recording" instead of "recording @a" *shm-q* +--- q do not show "recording @a" when recording a macro *shm-q* --- F don't give the file info when editing a file, like *shm-F* --- `:silent` was used for the command --- S do not show search count message when searching, e.g. *shm-S* -- cgit From 1c7b0b9d5f874fe962a8e63d9e8db7e576ab0d48 Mon Sep 17 00:00:00 2001 From: Maria José Solano Date: Mon, 12 Feb 2024 20:15:27 -0800 Subject: docs: stricter bufname and bufnr types (#27454) --- runtime/lua/vim/_meta/vimfn.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index acf3750500..224cecf144 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -582,7 +582,7 @@ function vim.fn.bufloaded(buf) end --- echo bufname("file2") " name of buffer where "file2" matches. --- < --- ---- @param buf? any +--- @param buf? integer|string --- @return string function vim.fn.bufname(buf) end @@ -599,7 +599,7 @@ function vim.fn.bufname(buf) end --- number necessarily exist, because ":bwipeout" may have removed --- them. Use bufexists() to test for the existence of a buffer. --- ---- @param buf? any +--- @param buf? integer|string --- @param create? any --- @return integer function vim.fn.bufnr(buf, create) end -- cgit From 309c36d3c9f80e2999b8a66c8a2a1ea640e84562 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Tue, 13 Feb 2024 02:33:09 -0500 Subject: docs(builtin): fix lua types for vim.fn.sign_getplaced Per :help sign_getplaced(): - Parameter {dict}: lnum also accepts integer as well as string - Return value: item has field bufnr, not buf --- runtime/lua/vim/_meta/builtin_types.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua index e74cf86173..0bbc3e9bc8 100644 --- a/runtime/lua/vim/_meta/builtin_types.lua +++ b/runtime/lua/vim/_meta/builtin_types.lua @@ -81,10 +81,10 @@ --- @class vim.fn.sign_getplaced.dict --- @field group? string --- @field id? integer ---- @field lnum? string +--- @field lnum? string|integer --- @class vim.fn.sign_getplaced.ret.item ---- @field buf integer +--- @field bufnr integer --- @field signs vim.fn.sign[] --- @class vim.fn.sign_place.dict -- cgit From 1a3a8d903e9705ce41867e1cbc629a85c7cb6252 Mon Sep 17 00:00:00 2001 From: bfredl Date: Sun, 11 Feb 2024 19:13:38 +0100 Subject: refactor(lua): use a keyset for vim.diff opts parsing --- runtime/lua/vim/_meta/api_keysets.lua | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 0442a89e3f..ab0d3aafe8 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -297,3 +297,17 @@ error('Cannot require a meta file') --- @field end_row? integer --- @field start_vcol? integer --- @field end_vcol? integer + +--- @class vim.api.keyset.xdl_diff +--- @field on_hunk? function +--- @field result_type? string +--- @field algorithm? string +--- @field ctxlen? integer +--- @field interhunkctxlen? integer +--- @field linematch? any +--- @field ignore_whitespace? boolean +--- @field ignore_whitespace_change? boolean +--- @field ignore_whitespace_change_at_eol? boolean +--- @field ignore_cr_at_eol? boolean +--- @field ignore_blank_lines? boolean +--- @field indent_heuristic? boolean -- cgit From 35f453f65df2cab4eaeda99c205d1fda235b7bc9 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 10:53:51 +0000 Subject: fix: type warnings in shared.lua --- runtime/lua/vim/_meta/builtin.lua | 1 + runtime/lua/vim/_meta/misc.lua | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index dd849e5247..a422a65792 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -83,6 +83,7 @@ function vim.in_fast_event() end --- --- Note: If numeric keys are present in the table, Nvim ignores the metatable --- marker and converts the dict to a list/array anyway. +--- @return table function vim.empty_dict() end --- Sends {event} to {channel} via |RPC| and returns immediately. If {channel} diff --git a/runtime/lua/vim/_meta/misc.lua b/runtime/lua/vim/_meta/misc.lua index 0d70e16314..ab80e18434 100644 --- a/runtime/lua/vim/_meta/misc.lua +++ b/runtime/lua/vim/_meta/misc.lua @@ -10,6 +10,7 @@ --- vim.fn[func]({...}) --- ``` --- ---- @param func fun() +--- @param func string --- @param ... any +--- @return any function vim.call(func, ...) end -- cgit From 55a4aa41bb27aa9439fea11c4ebcfec2ee87844d Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Thu, 15 Feb 2024 19:56:58 -0600 Subject: docs: document breaking change for nvim_create_autocmd callback (#27484) https://github.com/neovim/neovim/pull/27428 changed the semantics of callbacks passed to nvim_create_autocmd such that any truthy value will delete the autocommand (rather than just the literal boolean value `true`). Update the documentation accordingly and add an entry to `news.txt`. The behavior is now consistent between nvim_create_autocmd and nvim_buf_attach. --- runtime/lua/vim/_meta/api.lua | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index f46ab8023f..0978f0acf5 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -155,8 +155,9 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return `true` to ---- detach. Args: +--- • on_lines: Lua callback invoked on change. Return a +--- truthy value (not `false` or `nil`) +--- to detach. Args: --- • the string "lines" --- • buffer handle --- • b:changedtick @@ -169,7 +170,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- --- • on_bytes: Lua callback invoked on change. This --- callback receives more granular information about the ---- change compared to on_lines. Return `true` to +--- change compared to on_lines. Return a truthy value +--- (not `false` or `nil`) to --- detach. Args: --- • the string "bytes" --- • buffer handle @@ -863,9 +865,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- troubleshooting). --- • callback (function|string) optional: Lua function (or --- Vimscript function name, if string) called when the ---- event(s) is triggered. Lua callback can return true to ---- delete the autocommand, and receives a table argument with ---- these keys: +--- event(s) is triggered. Lua callback can return a truthy +--- value (not `false` or `nil`) to delete the +--- autocommand. Receives a table argument with these keys: --- • id: (number) autocommand id --- • event: (string) name of the triggered event --- `autocmd-events` -- cgit From a9f578b7a5edbca9aa01548f37341c2b97b57cda Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Mon, 19 Feb 2024 11:22:00 +0800 Subject: docs: improve 'tabline' click label docs (#27529) --- runtime/lua/vim/_meta/options.lua | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 835bd95a3a..5a9215fa9e 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -6525,16 +6525,17 @@ vim.wo.stc = vim.wo.statuscolumn --- ) - End of item group. No width fields allowed. --- T N For 'tabline': start of tab page N label. Use %T or %X to end --- the label. Clicking this label with left mouse button switches ---- to the specified tab page. +--- to the specified tab page, while clicking it with middle mouse +--- button closes the specified tab page. --- X N For 'tabline': start of close tab N label. Use %X or %T to end --- the label, e.g.: %3Xclose%X. Use %999X for a "close current ---- tab" label. Clicking this label with left mouse button closes ---- specified tab page. ---- @ N Start of execute function label. Use %X or %T to ---- end the label, e.g.: %10@SwitchBuffer@foo.c%X. Clicking this ---- label runs specified function: in the example when clicking once ---- using left mouse button on "foo.c" "SwitchBuffer(10, 1, 'l', ---- ' ')" expression will be run. Function receives the +--- tab" label. Clicking this label with left mouse button closes +--- the specified tab page. +--- @ N Start of execute function label. Use %X or %T to end the label, +--- e.g.: %10@SwitchBuffer@foo.c%X. Clicking this label runs the +--- specified function: in the example when clicking once using left +--- mouse button on "foo.c", a `SwitchBuffer(10, 1, 'l', ' ')` +--- expression will be run. The specified function receives the --- following arguments in order: --- 1. minwid field value or zero if no N was specified --- 2. number of mouse clicks to detect multiple clicks -- cgit From a0790558c3097f2813c56e404af30c3e2d8b8983 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 20 Feb 2024 19:53:49 +0800 Subject: fix(extmarks): priority order of inline and non-inline virt_text (#27532) --- runtime/lua/vim/_meta/api.lua | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 0978f0acf5..31ef3dd64b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -576,9 +576,10 @@ function vim.api.nvim_buf_line_count(buffer) end --- hidden marks, an "invalid" key is added to the "details" --- array of `nvim_buf_get_extmarks()` and family. If --- "undo_restore" is false, the extmark is deleted instead. ---- • priority: a priority value for the highlight group or sign ---- attribute. For example treesitter highlighting uses a ---- value of 100. +--- • priority: a priority value for the highlight group, sign +--- attribute or virtual text. For virtual text, item with +--- highest priority is drawn last. For example treesitter +--- highlighting uses a value of 100. --- • strict: boolean that indicates extmark should not be --- placed if the line or column value is past the end of the --- buffer or end of the line respectively. Defaults to true. -- cgit From 6d8bbfe19df2175637a1e47ac1aafb0e96e35b38 Mon Sep 17 00:00:00 2001 From: rktjmp Date: Thu, 22 Feb 2024 00:25:08 +1100 Subject: docs: remove mention of foreground/background/special keys in nvim_set_hl (#27558) To align the output of `nvim_get_hl` with its documentation -- which points to `nvim_set_hl`, remove mentions of the keys `foreground`, `background` and `special`. The long keys are are still supported (via fallback checks inside `dict2hlattrs`), but the `fg`, `bg` and `sp` keys are preferenced. --- runtime/lua/vim/_meta/api.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 31ef3dd64b..cfdb65c2b5 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1819,9 +1819,9 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- activate them. --- @param name string Highlight group name, e.g. "ErrorMsg" --- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys: ---- • fg (or foreground): color name or "#RRGGBB", see note. ---- • bg (or background): color name or "#RRGGBB", see note. ---- • sp (or special): color name or "#RRGGBB" +--- • fg: color name or "#RRGGBB", see note. +--- • bg: color name or "#RRGGBB", see note. +--- • sp: color name or "#RRGGBB" --- • blend: integer between 0 and 100 --- • bold: boolean --- • standout: boolean -- cgit From 1c032ad703a19cd5c8498ee95f9352df87a91139 Mon Sep 17 00:00:00 2001 From: altermo <107814000+altermo@users.noreply.github.com> Date: Tue, 6 Feb 2024 11:52:42 +0100 Subject: feat(extmark): window scoped extmark Co-authored-by: zeertzjq --- runtime/lua/vim/_meta/api.lua | 22 ++++++++++++++++++++++ runtime/lua/vim/_meta/api_keysets.lua | 1 + 2 files changed, 23 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index cfdb65c2b5..998608ae16 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -613,6 +613,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- • url: A URL to associate with this extmark. In the TUI, the --- OSC 8 control sequence is used to generate a clickable --- hyperlink to this URL. +--- • scoped: boolean that indicates that the extmark should +--- only be displayed in the namespace scope. (experimental) --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end @@ -1982,6 +1984,13 @@ function vim.api.nvim_tabpage_set_var(tabpage, name, value) end --- @param win integer Window handle, must already belong to {tabpage} function vim.api.nvim_tabpage_set_win(tabpage, win) end +--- Adds the namespace scope to the window. +--- +--- @param window integer Window handle, or 0 for current window +--- @param ns_id integer the namespace to add +--- @return boolean +function vim.api.nvim_win_add_ns(window, ns_id) end + --- Calls a function with window as temporary current window. --- --- @param window integer Window handle, or 0 for current window @@ -2032,6 +2041,12 @@ function vim.api.nvim_win_get_cursor(window) end --- @return integer function vim.api.nvim_win_get_height(window) end +--- Gets all the namespaces scopes associated with a window. +--- +--- @param window integer Window handle, or 0 for current window +--- @return integer[] +function vim.api.nvim_win_get_ns(window) end + --- Gets the window number --- --- @param window integer Window handle, or 0 for current window @@ -2084,6 +2099,13 @@ function vim.api.nvim_win_hide(window) end --- @return boolean function vim.api.nvim_win_is_valid(window) end +--- Removes the namespace scope from the window. +--- +--- @param window integer Window handle, or 0 for current window +--- @param ns_id integer the namespace to remove +--- @return boolean +function vim.api.nvim_win_remove_ns(window, ns_id) end + --- Sets the current buffer in a window, without side effects --- --- @param window integer Window handle, or 0 for current window diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index ab0d3aafe8..37e4372196 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -252,6 +252,7 @@ error('Cannot require a meta file') --- @field ui_watched? boolean --- @field undo_restore? boolean --- @field url? string +--- @field scoped? boolean --- @field _subpriority? integer --- @class vim.api.keyset.user_command -- cgit From 20e4001eeedc80b1f2857fcaca81f7a211a09b40 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Thu, 22 Feb 2024 20:32:52 +0800 Subject: vim-patch:9.1.0120: hard to get visual region using Vim script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: hard to get visual region using Vim script Solution: Add getregion() Vim script function (Shougo Matsushita, Jakub Łuczyński) closes: vim/vim#13998 closes: vim/vim#11579 https://github.com/vim/vim/commit/3f905ab3c4f66562f4a224bf00f49d98a0b0da91 Cherry-pick changes from patch 9.1.0122, with :echom instead of :echow. Co-authored-by: Shougo Matsushita Co-authored-by: Jakub Łuczyński --- runtime/lua/vim/_meta/vimfn.lua | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 224cecf144..527113c016 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -3525,6 +3525,46 @@ function vim.fn.getreg(regname, list) end --- @return table function vim.fn.getreginfo(regname) end +--- Returns the list of strings from {pos1} to {pos2} as if it's +--- selected in visual mode of {type}. +--- For possible values of {pos1} and {pos2} see |line()|. +--- {type} is the selection type: +--- "v" for |charwise| mode +--- "V" for |linewise| mode +--- "" for |blockwise-visual| mode +--- You can get the last selection type by |visualmode()|. +--- If Visual mode is active, use |mode()| to get the Visual mode +--- (e.g., in a |:vmap|). +--- This function uses the line and column number from the +--- specified position. +--- It is useful to get text starting and ending in different +--- columns, such as |charwise-visual| selection. +--- +--- Note that: +--- - Order of {pos1} and {pos2} doesn't matter, it will always +--- return content from the upper left position to the lower +--- right position. +--- - If 'virtualedit' is enabled and selection is past the end of +--- line, resulting lines are filled with blanks. +--- - If the selection starts or ends in the middle of a multibyte +--- character, it is not included but its selected part is +--- substituted with spaces. +--- - If {pos1} or {pos2} equals "v" (see |line()|) and it is not in +--- |visual-mode|, an empty list is returned. +--- - If {pos1}, {pos2} or {type} is an invalid string, an empty +--- list is returned. +--- +--- Examples: > +--- :xnoremap +--- \ echom getregion('v', '.', mode()) +--- < +--- +--- @param pos1 string +--- @param pos2 string +--- @param type string +--- @return string[] +function vim.fn.getregion(pos1, pos2, type) end + --- The result is a String, which is type of register {regname}. --- The value will be one of: --- "v" for |charwise| text -- cgit From 06df895e71720b65f98b6b9c579ca5918a12bc04 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 23 Feb 2024 06:35:40 +0800 Subject: vim-patch:9.1.0126: Internal error when using upper-case mark in getregion() Problem: Internal error when passing mark in another buffer to getregion(). Solution: Don't allow marks in another buffer (zeertzjq) closes: vim/vim#14076 Internal error when passing mark in another buffer to getregion() https://github.com/vim/vim/commit/421b597470c118871c7081de00dd065e0e000b7e --- runtime/lua/vim/_meta/vimfn.lua | 2 ++ 1 file changed, 2 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 527113c016..623ce2bc0f 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -3553,6 +3553,8 @@ function vim.fn.getreginfo(regname) end --- |visual-mode|, an empty list is returned. --- - If {pos1}, {pos2} or {type} is an invalid string, an empty --- list is returned. +--- - If {pos1} or {pos2} is a mark in different buffer, an empty +--- list is returned. --- --- Examples: > --- :xnoremap -- cgit From 9418381ccca5bf749b2f10b8a31d6e0900898ffa Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Sat, 24 Feb 2024 17:55:32 +0800 Subject: vim-patch:a35235e824bb (#27598) runtime(doc) Update help text for matchbufline() and matchstrlist() closes: vim/vim#14080 https://github.com/vim/vim/commit/a35235e824bb77df0cebdb2bd290e13f1201b292 Co-authored-by: Yegappan Lakshmanan --- runtime/lua/vim/_meta/vimfn.lua | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 623ce2bc0f..07e6d42e1c 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -5356,6 +5356,7 @@ function vim.fn.mapset(dict) end --- Note that when {count} is added the way {start} works changes, --- see above. --- +--- *match-pattern* --- See |pattern| for the patterns that are accepted. --- The 'ignorecase' option is used to set the ignore-caseness of --- the pattern. 'smartcase' is NOT used. The matching is always @@ -5514,6 +5515,9 @@ function vim.fn.matcharg(nr) end --- This function works only for loaded buffers. First call --- |bufload()| if needed. --- +--- See |match-pattern| for information about the effect of some +--- option settings on the pattern. +--- --- When {buf} is not a valid buffer, the buffer is not loaded or --- {lnum} or {end} is not valid then an error is given and an --- empty |List| is returned. @@ -5727,6 +5731,9 @@ function vim.fn.matchstr(expr, pat, start, count) end --- submatches a List of submatches. Present only if --- "submatches" is set to v:true in {dict}. --- +--- See |match-pattern| for information about the effect of some +--- option settings on the pattern. +--- --- Example: >vim --- :echo matchstrlist(['tik tok'], '\<\k\+\>') --- [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] -- cgit From c2ddef30e743d8c1de6d960bf230b8646cb49c7c Mon Sep 17 00:00:00 2001 From: Evgeni Chasnovski Date: Sun, 25 Feb 2024 02:45:34 +0200 Subject: docs: fix several misleading and superfluous wordings (#27609) --- runtime/lua/vim/_meta/api.lua | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 998608ae16..aee866f324 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -584,21 +584,16 @@ function vim.api.nvim_buf_line_count(buffer) end --- placed if the line or column value is past the end of the --- buffer or end of the line respectively. Defaults to true. --- • sign_text: string of length 1-2 used to display in the ---- sign column. Note: ranges are unsupported and decorations ---- are only applied to start_row +--- sign column. --- • sign_hl_group: name of the highlight group used to ---- highlight the sign column text. Note: ranges are ---- unsupported and decorations are only applied to start_row +--- highlight the sign column text. --- • number_hl_group: name of the highlight group used to ---- highlight the number column. Note: ranges are unsupported ---- and decorations are only applied to start_row +--- highlight the number column. --- • line_hl_group: name of the highlight group used to ---- highlight the whole line. Note: ranges are unsupported and ---- decorations are only applied to start_row +--- highlight the whole line. --- • cursorline_hl_group: name of the highlight group used to ---- highlight the line when the cursor is on the same line as ---- the mark and 'cursorline' is enabled. Note: ranges are ---- unsupported and decorations are only applied to start_row +--- highlight the sign column text when the cursor is on the +--- same line as the mark and 'cursorline' is enabled. --- • conceal: string which should be either empty or a single --- character. Enable concealing similar to `:syn-conceal`. --- When a character is supplied it is used as `:syn-cchar`. @@ -1807,7 +1802,7 @@ function vim.api.nvim_set_current_win(window) end --- • on_win: called when starting to redraw a specific window. --- ["win", winid, bufnr, topline, botline] --- • on_line: called for each buffer line being redrawn. (The ---- interaction with fold lines is subject to change) ["win", +--- interaction with fold lines is subject to change) ["line", --- winid, bufnr, row] --- • on_end: called at the end of a redraw cycle ["end", tick] function vim.api.nvim_set_decoration_provider(ns_id, opts) end -- cgit From 7ad2e3c64562bfb0ea2f7be305e4b0e6d2474d64 Mon Sep 17 00:00:00 2001 From: Maria José Solano Date: Tue, 27 Feb 2024 03:53:49 -0800 Subject: docs: fix type of setreg() argument {options} (#27631) --- runtime/lua/vim/_meta/vimfn.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 07e6d42e1c..779016f2d1 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -8172,7 +8172,7 @@ function vim.fn.setqflist(list, action, what) end --- --- @param regname string --- @param value any ---- @param options? table +--- @param options? string --- @return any function vim.fn.setreg(regname, value, options) end -- cgit From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 17:16:04 +0000 Subject: feat(docs): replace lua2dox.lua Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change). --- runtime/lua/vim/_meta/api.lua | 843 +++++++++++++++++++++----------------- runtime/lua/vim/_meta/builtin.lua | 116 +++--- runtime/lua/vim/_meta/json.lua | 2 +- runtime/lua/vim/_meta/lpeg.lua | 23 +- runtime/lua/vim/_meta/mpack.lua | 5 +- runtime/lua/vim/_meta/re.lua | 13 +- runtime/lua/vim/_meta/regex.lua | 2 - 7 files changed, 552 insertions(+), 452 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index aee866f324..d2f624fd97 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -38,6 +38,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end --- @private --- Returns object given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -47,6 +48,7 @@ function vim.api.nvim__id(obj) end --- @private --- Returns array given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -56,6 +58,7 @@ function vim.api.nvim__id_array(arr) end --- @private --- Returns dictionary given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -65,6 +68,7 @@ function vim.api.nvim__id_dictionary(dct) end --- @private --- Returns floating-point value given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -108,17 +112,20 @@ function vim.api.nvim__stats() end function vim.api.nvim__unpack(str) end --- Adds a highlight to buffer. +--- --- Useful for plugins that dynamically generate highlights to a buffer (like --- a semantic highlighter or linter). The function adds a single highlight to --- a buffer. Unlike `matchaddpos()` highlights follow changes to line --- numbering (as lines are inserted/removed above the highlighted line), like --- signs and marks do. +--- --- Namespaces are used for batch deletion/updating of a set of highlights. To --- create a namespace, use `nvim_create_namespace()` which returns a --- namespace id. Pass it in to this function as `ns_id` to add highlights to --- the namespace. All highlights in the same namespace can then be cleared --- with single call to `nvim_buf_clear_namespace()`. If the highlight never --- will be deleted by an API call, pass `ns_id = -1`. +--- --- As a shorthand, `ns_id = 0` can be used to create a new namespace for the --- highlight, the allocated id is then returned. If `hl_group` is the empty --- string no highlight is added, but a new `ns_id` is still returned. This is @@ -131,11 +138,12 @@ function vim.api.nvim__unpack(str) end --- @param line integer Line to highlight (zero-indexed) --- @param col_start integer Start of (byte-indexed) column range to highlight --- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to ---- highlight to end of line +--- highlight to end of line --- @return integer function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end --- Activates buffer-update events on a channel, or as Lua callbacks. +--- --- Example (Lua): capture buffer updates in a global `events` variable (use --- "vim.print(events)" to see its contents): --- @@ -148,6 +156,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- }) --- ``` --- +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param send_buffer boolean True if the initial notification should contain the --- whole buffer: first notification will be @@ -155,77 +164,70 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return a ---- truthy value (not `false` or `nil`) ---- to detach. Args: ---- • the string "lines" ---- • buffer handle ---- • b:changedtick ---- • first line that changed (zero-indexed) ---- • last line that was changed ---- • last line in the updated range ---- • byte count of previous contents ---- • deleted_codepoints (if `utf_sizes` is true) ---- • deleted_codeunits (if `utf_sizes` is true) ---- ---- • on_bytes: Lua callback invoked on change. This ---- callback receives more granular information about the ---- change compared to on_lines. Return a truthy value ---- (not `false` or `nil`) to ---- detach. Args: ---- • the string "bytes" ---- • buffer handle ---- • b:changedtick ---- • start row of the changed text (zero-indexed) ---- • start column of the changed text ---- • byte offset of the changed text (from the start of ---- the buffer) ---- • old end row of the changed text (offset from start ---- row) ---- • old end column of the changed text (if old end row ---- = 0, offset from start column) ---- • old end byte length of the changed text ---- • new end row of the changed text (offset from start ---- row) ---- • new end column of the changed text (if new end row ---- = 0, offset from start column) ---- • new end byte length of the changed text ---- ---- • on_changedtick: Lua callback invoked on changedtick ---- increment without text change. Args: ---- • the string "changedtick" ---- • buffer handle ---- • b:changedtick ---- ---- • on_detach: Lua callback invoked on detach. Args: ---- • the string "detach" ---- • buffer handle ---- ---- • on_reload: Lua callback invoked on reload. The entire ---- buffer content should be considered changed. Args: ---- • the string "reload" ---- • buffer handle ---- ---- • utf_sizes: include UTF-32 and UTF-16 size of the ---- replaced region, as args to `on_lines`. ---- • preview: also attach to command preview (i.e. ---- 'inccommand') events. +--- • on_lines: Lua callback invoked on change. Return a truthy +--- value (not `false` or `nil`) to detach. Args: +--- • the string "lines" +--- • buffer handle +--- • b:changedtick +--- • first line that changed (zero-indexed) +--- • last line that was changed +--- • last line in the updated range +--- • byte count of previous contents +--- • deleted_codepoints (if `utf_sizes` is true) +--- • deleted_codeunits (if `utf_sizes` is true) +--- • on_bytes: Lua callback invoked on change. This callback +--- receives more granular information about the change compared +--- to on_lines. Return a truthy value (not `false` or `nil`) to +--- detach. Args: +--- • the string "bytes" +--- • buffer handle +--- • b:changedtick +--- • start row of the changed text (zero-indexed) +--- • start column of the changed text +--- • byte offset of the changed text (from the start of the +--- buffer) +--- • old end row of the changed text (offset from start row) +--- • old end column of the changed text (if old end row = 0, +--- offset from start column) +--- • old end byte length of the changed text +--- • new end row of the changed text (offset from start row) +--- • new end column of the changed text (if new end row = 0, +--- offset from start column) +--- • new end byte length of the changed text +--- • on_changedtick: Lua callback invoked on changedtick +--- increment without text change. Args: +--- • the string "changedtick" +--- • buffer handle +--- • b:changedtick +--- • on_detach: Lua callback invoked on detach. Args: +--- • the string "detach" +--- • buffer handle +--- • on_reload: Lua callback invoked on reload. The entire buffer +--- content should be considered changed. Args: +--- • the string "reload" +--- • buffer handle +--- • utf_sizes: include UTF-32 and UTF-16 size of the replaced +--- region, as args to `on_lines`. +--- • preview: also attach to command preview (i.e. 'inccommand') +--- events. --- @return boolean function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- call a function with buffer as temporary current buffer +--- --- This temporarily switches current buffer to "buffer". If the current --- window already shows "buffer", the window is not switched If a window --- inside the current tabpage (including a float) already shows the buffer --- One of these windows will be set as current window temporarily. Otherwise --- a temporary scratch window (called the "autocmd window" for historical --- reasons) will be used. +--- --- This is useful e.g. to call Vimscript functions that only work with the --- current buffer/window currently, like `termopen()`. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable ---- only) +--- only) --- @return any function vim.api.nvim_buf_call(buffer, fun) end @@ -238,14 +240,15 @@ function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) e --- Clears `namespace`d objects (highlights, `extmarks`, virtual text) from a --- region. +--- --- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire --- buffer, specify line_start=0 and line_end=-1. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace to clear, or -1 to clear all namespaces. --- @param line_start integer Start of range of lines to clear ---- @param line_end integer End of range of lines to clear (exclusive) or -1 to ---- clear to end of buffer. +--- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear +--- to end of buffer. function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) end --- Creates a buffer-local command `user-commands`. @@ -279,6 +282,7 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end function vim.api.nvim_buf_del_mark(buffer, name) end --- 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. --- @@ -296,8 +300,8 @@ function vim.api.nvim_buf_del_var(buffer, name) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param opts vim.api.keyset.buf_delete Optional parameters. Keys: ---- • force: Force deletion and ignore unsaved changes. ---- • unload: Unloaded only, do not delete. See `:bunload` +--- • force: Force deletion and ignore unsaved changes. +--- • unload: Unloaded only, do not delete. See `:bunload` function vim.api.nvim_buf_delete(buffer, opts) end --- Gets a changed tick of a buffer @@ -319,14 +323,15 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id --- @param opts vim.api.keyset.get_extmark Optional parameters. Keys: ---- • details: Whether to include the details dict ---- • hl_name: Whether to include highlight group name instead ---- of id, true if omitted +--- • details: Whether to include the details dict +--- • hl_name: Whether to include highlight group name instead of +--- id, true if omitted --- @return vim.api.keyset.get_extmark_item function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by --- buffer positions (inclusive, 0-indexed `api-indexing`). +--- --- Region can be given as (row,col) tuples, or valid extmark ids (whose --- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) --- respectively, thus the following are equivalent: @@ -338,12 +343,15 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- --- If `end` is less than `start`, traversal works backwards. (Useful with --- `limit`, to get the first marks prior to a given position.) +--- --- Note: when using extmark ranges (marks with a end_row/end_col position) --- the `overlap` option might be useful. Otherwise only the start position of --- an extmark will be considered. +--- --- Note: legacy signs placed through the `:sign` commands are implemented as --- extmarks and will show up here. Their details array will contain a --- `sign_name` field. +--- --- Example: --- --- ```lua @@ -361,23 +369,23 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- vim.print(ms) --- ``` --- +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all ---- namespaces +--- namespaces --- @param start any Start of range: a 0-indexed (row, col) or valid extmark id ---- (whose position defines the bound). `api-indexing` +--- (whose position defines the bound). `api-indexing` --- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid ---- extmark id (whose position defines the bound). ---- `api-indexing` +--- extmark id (whose position defines the bound). `api-indexing` --- @param opts vim.api.keyset.get_extmarks Optional parameters. Keys: ---- • limit: Maximum number of marks to return ---- • details: Whether to include the details dict ---- • hl_name: Whether to include highlight group name instead ---- of id, true if omitted ---- • overlap: Also include marks which overlap the range, even ---- if their start position is less than `start` ---- • type: Filter marks by type: "highlight", "sign", ---- "virt_text" and "virt_lines" +--- • limit: Maximum number of marks to return +--- • details: Whether to include the details dict +--- • hl_name: Whether to include highlight group name instead of +--- id, true if omitted +--- • overlap: Also include marks which overlap the range, even if +--- their start position is less than `start` +--- • type: Filter marks by type: "highlight", "sign", "virt_text" +--- and "virt_lines" --- @return vim.api.keyset.get_extmark_item[] function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end @@ -389,9 +397,11 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. +--- --- Indexing is zero-based, end-exclusive. Negative indices are interpreted as --- length+1+index: -1 refers to the index past the end. So to get the last --- element use start=-2 and end=-1. +--- --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- @@ -405,6 +415,7 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end --- Returns a `(row,col)` tuple representing the position of the named mark. --- "End of line" column position is returned as `v:maxcol` (big number). See --- `mark-motions`. +--- --- Marks are (1,0)-indexed. `api-indexing` --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -424,10 +435,12 @@ function vim.api.nvim_buf_get_name(buffer) end function vim.api.nvim_buf_get_number(buffer) end --- Returns the byte offset of a line (0-indexed). `api-indexing` +--- --- Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. --- 'fileformat' and 'fileencoding' are ignored. The line index just after the --- last line gives the total byte-count of the buffer. A final EOL byte is --- counted if it would be written, see 'eol'. +--- --- Unlike `line2byte()`, throws error for out-of-bounds indexing. Returns -1 --- for unloaded buffer. --- @@ -443,10 +456,13 @@ function vim.api.nvim_buf_get_offset(buffer, index) end function vim.api.nvim_buf_get_option(buffer, name) end --- Gets a range from the buffer. +--- --- This differs from `nvim_buf_get_lines()` in that it allows retrieving only --- portions of a line. +--- --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. +--- --- Prefer `nvim_buf_get_lines()` when retrieving entire lines. --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -485,13 +501,16 @@ function vim.api.nvim_buf_is_valid(buffer) end function vim.api.nvim_buf_line_count(buffer) end --- Creates or updates an `extmark`. +--- --- By default a new extmark is created when no id is passed in, but it is --- also possible to create a new mark by passing in a previously unused id or --- move an existing mark by passing in its id. The caller must then keep --- track of existing and unused ids itself. (Useful over RPC, to avoid --- waiting for the return value.) +--- --- Using the optional arguments, it is possible to use this to highlight a --- range of text, and also to associate virtual text to the mark. +--- --- If present, the position defined by `end_col` and `end_row` should be --- after the start position in order for the extmark to cover a range. An --- earlier end position is not an error, but then it behaves like an empty @@ -502,114 +521,110 @@ function vim.api.nvim_buf_line_count(buffer) end --- @param line integer Line where to place the mark, 0-based. `api-indexing` --- @param col integer Column where to place the mark, 0-based. `api-indexing` --- @param opts vim.api.keyset.set_extmark Optional parameters. ---- • id : id of the extmark to edit. ---- • end_row : ending line of the mark, 0-based inclusive. ---- • end_col : ending col of the mark, 0-based exclusive. ---- • hl_group : name of the highlight group used to highlight ---- this mark. ---- • hl_eol : when true, for a multiline highlight covering the ---- EOL of a line, continue the highlight for the rest of the ---- screen line (just like for diff and cursorline highlight). ---- • virt_text : virtual text to link to this mark. A list of ---- [text, highlight] tuples, each representing a text chunk ---- with specified highlight. `highlight` element can either ---- be a single highlight group, or an array of multiple ---- highlight groups that will be stacked (highest priority ---- last). A highlight group can be supplied either as a ---- string or as an integer, the latter which can be obtained ---- using `nvim_get_hl_id_by_name()`. ---- • virt_text_pos : position of virtual text. Possible values: ---- • "eol": right after eol character (default). ---- • "overlay": display over the specified column, without ---- shifting the underlying text. ---- • "right_align": display right aligned in the window. ---- • "inline": display at the specified column, and shift the ---- buffer text to the right as needed. ---- ---- • virt_text_win_col : position the virtual text at a fixed ---- window column (starting from the first text column of the ---- screen line) instead of "virt_text_pos". ---- • virt_text_hide : hide the virtual text when the background ---- text is selected or hidden because of scrolling with ---- 'nowrap' or 'smoothscroll'. Currently only affects ---- "overlay" virt_text. ---- • virt_text_repeat_linebreak : repeat the virtual text on ---- wrapped lines. ---- • hl_mode : control how highlights are combined with the ---- highlights of the text. Currently only affects virt_text ---- highlights, but might affect `hl_group` in ---- later versions. ---- • "replace": only show the virt_text color. This is the ---- default. ---- • "combine": combine with background text color. ---- • "blend": blend with background text color. Not supported ---- for "inline" virt_text. ---- ---- • virt_lines : virtual lines to add next to this mark This ---- should be an array over lines, where each line in turn is ---- an array over [text, highlight] tuples. In general, buffer ---- and window options do not affect the display of the text. ---- In particular 'wrap' and 'linebreak' options do not take ---- effect, so the number of extra screen lines will always ---- match the size of the array. However the 'tabstop' buffer ---- option is still used for hard tabs. By default lines are ---- placed below the buffer line containing the mark. ---- • virt_lines_above: place virtual lines above instead. ---- • virt_lines_leftcol: Place extmarks in the leftmost column ---- of the window, bypassing sign and number columns. ---- • ephemeral : for use with `nvim_set_decoration_provider()` ---- callbacks. The mark will only be used for the current ---- redraw cycle, and not be permantently stored in the ---- buffer. ---- • right_gravity : boolean that indicates the direction the ---- extmark will be shifted in when new text is inserted (true ---- for right, false for left). Defaults to true. ---- • end_right_gravity : boolean that indicates the direction ---- the extmark end position (if it exists) will be shifted in ---- when new text is inserted (true for right, false for ---- left). Defaults to false. ---- • undo_restore : Restore the exact position of the mark if ---- text around the mark was deleted and then restored by ---- undo. Defaults to true. ---- • invalidate : boolean that indicates whether to hide the ---- extmark if the entirety of its range is deleted. For ---- hidden marks, an "invalid" key is added to the "details" ---- array of `nvim_buf_get_extmarks()` and family. If ---- "undo_restore" is false, the extmark is deleted instead. ---- • priority: a priority value for the highlight group, sign ---- attribute or virtual text. For virtual text, item with ---- highest priority is drawn last. For example treesitter ---- highlighting uses a value of 100. ---- • strict: boolean that indicates extmark should not be ---- placed if the line or column value is past the end of the ---- buffer or end of the line respectively. Defaults to true. ---- • sign_text: string of length 1-2 used to display in the ---- sign column. ---- • sign_hl_group: name of the highlight group used to ---- highlight the sign column text. ---- • number_hl_group: name of the highlight group used to ---- highlight the number column. ---- • line_hl_group: name of the highlight group used to ---- highlight the whole line. ---- • cursorline_hl_group: name of the highlight group used to ---- highlight the sign column text when the cursor is on the ---- same line as the mark and 'cursorline' is enabled. ---- • conceal: string which should be either empty or a single ---- character. Enable concealing similar to `:syn-conceal`. ---- When a character is supplied it is used as `:syn-cchar`. ---- "hl_group" is used as highlight for the cchar if provided, ---- otherwise it defaults to `hl-Conceal`. ---- • spell: boolean indicating that spell checking should be ---- performed within this extmark ---- • ui_watched: boolean that indicates the mark should be ---- drawn by a UI. When set, the UI will receive win_extmark ---- events. Note: the mark is positioned by virt_text ---- attributes. Can be used together with virt_text. ---- • url: A URL to associate with this extmark. In the TUI, the ---- OSC 8 control sequence is used to generate a clickable ---- hyperlink to this URL. ---- • scoped: boolean that indicates that the extmark should ---- only be displayed in the namespace scope. (experimental) +--- • id : id of the extmark to edit. +--- • end_row : ending line of the mark, 0-based inclusive. +--- • end_col : ending col of the mark, 0-based exclusive. +--- • hl_group : name of the highlight group used to highlight +--- this mark. +--- • hl_eol : when true, for a multiline highlight covering the +--- EOL of a line, continue the highlight for the rest of the +--- screen line (just like for diff and cursorline highlight). +--- • virt_text : virtual text to link to this mark. A list of +--- [text, highlight] tuples, each representing a text chunk +--- with specified highlight. `highlight` element can either be +--- a single highlight group, or an array of multiple highlight +--- groups that will be stacked (highest priority last). A +--- highlight group can be supplied either as a string or as an +--- integer, the latter which can be obtained using +--- `nvim_get_hl_id_by_name()`. +--- • virt_text_pos : position of virtual text. Possible values: +--- • "eol": right after eol character (default). +--- • "overlay": display over the specified column, without +--- shifting the underlying text. +--- • "right_align": display right aligned in the window. +--- • "inline": display at the specified column, and shift the +--- buffer text to the right as needed. +--- • virt_text_win_col : position the virtual text at a fixed +--- window column (starting from the first text column of the +--- screen line) instead of "virt_text_pos". +--- • virt_text_hide : hide the virtual text when the background +--- text is selected or hidden because of scrolling with +--- 'nowrap' or 'smoothscroll'. Currently only affects "overlay" +--- virt_text. +--- • virt_text_repeat_linebreak : repeat the virtual text on +--- wrapped lines. +--- • hl_mode : control how highlights are combined with the +--- highlights of the text. Currently only affects virt_text +--- highlights, but might affect `hl_group` in later versions. +--- • "replace": only show the virt_text color. This is the +--- default. +--- • "combine": combine with background text color. +--- • "blend": blend with background text color. Not supported +--- for "inline" virt_text. +--- • virt_lines : virtual lines to add next to this mark This +--- should be an array over lines, where each line in turn is an +--- array over [text, highlight] tuples. In general, buffer and +--- window options do not affect the display of the text. In +--- particular 'wrap' and 'linebreak' options do not take +--- effect, so the number of extra screen lines will always +--- match the size of the array. However the 'tabstop' buffer +--- option is still used for hard tabs. By default lines are +--- placed below the buffer line containing the mark. +--- • virt_lines_above: place virtual lines above instead. +--- • virt_lines_leftcol: Place extmarks in the leftmost column of +--- the window, bypassing sign and number columns. +--- • ephemeral : for use with `nvim_set_decoration_provider()` +--- callbacks. The mark will only be used for the current redraw +--- cycle, and not be permantently stored in the buffer. +--- • right_gravity : boolean that indicates the direction the +--- extmark will be shifted in when new text is inserted (true +--- for right, false for left). Defaults to true. +--- • end_right_gravity : boolean that indicates the direction the +--- extmark end position (if it exists) will be shifted in when +--- new text is inserted (true for right, false for left). +--- Defaults to false. +--- • undo_restore : Restore the exact position of the mark if +--- text around the mark was deleted and then restored by undo. +--- Defaults to true. +--- • invalidate : boolean that indicates whether to hide the +--- extmark if the entirety of its range is deleted. For hidden +--- marks, an "invalid" key is added to the "details" array of +--- `nvim_buf_get_extmarks()` and family. If "undo_restore" is +--- false, the extmark is deleted instead. +--- • priority: a priority value for the highlight group, sign +--- attribute or virtual text. For virtual text, item with +--- highest priority is drawn last. For example treesitter +--- highlighting uses a value of 100. +--- • strict: boolean that indicates extmark should not be placed +--- if the line or column value is past the end of the buffer or +--- end of the line respectively. Defaults to true. +--- • sign_text: string of length 1-2 used to display in the sign +--- column. +--- • sign_hl_group: name of the highlight group used to highlight +--- the sign column text. +--- • number_hl_group: name of the highlight group used to +--- highlight the number column. +--- • line_hl_group: name of the highlight group used to highlight +--- the whole line. +--- • cursorline_hl_group: name of the highlight group used to +--- highlight the sign column text when the cursor is on the +--- same line as the mark and 'cursorline' is enabled. +--- • conceal: string which should be either empty or a single +--- character. Enable concealing similar to `:syn-conceal`. When +--- a character is supplied it is used as `:syn-cchar`. +--- "hl_group" is used as highlight for the cchar if provided, +--- otherwise it defaults to `hl-Conceal`. +--- • spell: boolean indicating that spell checking should be +--- performed within this extmark +--- • ui_watched: boolean that indicates the mark should be drawn +--- by a UI. When set, the UI will receive win_extmark events. +--- Note: the mark is positioned by virt_text attributes. Can be +--- used together with virt_text. +--- • url: A URL to associate with this extmark. In the TUI, the +--- OSC 8 control sequence is used to generate a clickable +--- hyperlink to this URL. +--- • scoped: boolean that indicates that the extmark should only +--- be displayed in the namespace scope. (experimental) --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end @@ -623,11 +638,14 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- Sets (replaces) a line-range in the buffer. +--- --- Indexing is zero-based, end-exclusive. Negative indices are interpreted as --- length+1+index: -1 refers to the index past the end. So to change or --- delete the last element use start=-2 and end=-1. +--- --- To insert lines at a given index, set `start` and `end` to the same index. --- To delete a range of lines, set `replacement` to an empty array. +--- --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- @@ -640,6 +658,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- Sets a named mark in the given buffer, all marks are allowed --- file/uppercase, visual, last change, etc. See `mark-motions`. +--- --- Marks are (1,0)-indexed. `api-indexing` --- --- @param buffer integer Buffer to set the mark on @@ -663,16 +682,21 @@ function vim.api.nvim_buf_set_name(buffer, name) end function vim.api.nvim_buf_set_option(buffer, name, value) end --- Sets (replaces) a range in the buffer +--- --- This is recommended over `nvim_buf_set_lines()` when only modifying parts --- of a line, as extmarks will be preserved on non-modified parts of the --- touched lines. +--- --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. +--- --- To insert text at a given `(row, column)` location, use `start_row = --- end_row = row` and `start_col = end_col = col`. To delete the text in a --- range, use `replacement = {}`. +--- --- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire --- lines. +--- --- Prefer `nvim_put()` if you want to insert text at the cursor position. --- --- @param buffer integer Buffer handle, or 0 for current buffer @@ -700,6 +724,7 @@ function vim.api.nvim_buf_set_var(buffer, name, value) end function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end --- Calls a Vimscript `Dictionary-function` with the given arguments. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param dict any Dictionary, or String evaluating to a Vimscript `self` dict @@ -709,6 +734,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e function vim.api.nvim_call_dict_function(dict, fn, args) end --- Calls a Vimscript function with the given arguments. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param fn string Function to call @@ -720,6 +746,7 @@ function vim.api.nvim_call_function(fn, args) end --- process. For the stdio channel `channel-stdio`, it writes to Nvim's --- stdout. For an internal terminal instance (`nvim_open_term()`) it writes --- directly to terminal output. See `channel-bytes` for more information. +--- --- This function writes raw data, not RPC messages. If the channel was --- created with `rpc=true` then the channel expects RPC messages, use --- `vim.rpcnotify()` and `vim.rpcrequest()` instead. @@ -736,42 +763,41 @@ function vim.api.nvim_chan_send(chan, data) end --- • 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. function vim.api.nvim_clear_autocmds(opts) end --- Executes an Ex command. +--- --- Unlike `nvim_command()` this command takes a structured Dictionary 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. --- --- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dictionary 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. +--- same values as the return value of `nvim_parse_cmd()` except +--- "addr", "nargs" and "nextcmd" which are ignored if provided. +--- All values except for "cmd" are optional. --- @param opts vim.api.keyset.cmd_opts Optional parameters. --- • output: (boolean, default false) Whether to return command --- output. @@ -779,7 +805,9 @@ function vim.api.nvim_clear_autocmds(opts) end function vim.api.nvim_cmd(cmd, opts) end --- Executes an Ex command. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. +--- --- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate --- multiple lines of Vim script or an Ex command directly, use --- `nvim_exec2()`. To construct an Ex command using a structured format and @@ -800,11 +828,12 @@ function vim.api.nvim_command_output(command) end --- --- @param index integer the completion candidate index --- @param opts vim.api.keyset.complete_set Optional parameters. ---- • info: (string) info text. +--- • info: (string) info text. --- @return table function vim.api.nvim_complete_set(index, opts) end --- Create or get an autocommand group `autocmd-groups`. +--- --- To get an existing group id, do: --- --- ```lua @@ -813,6 +842,7 @@ function vim.api.nvim_complete_set(index, opts) end --- }) --- ``` --- +--- --- @param name string String: The name of the group --- @param opts vim.api.keyset.create_augroup Dictionary Parameters --- • clear (bool) optional: defaults to true. Clear existing @@ -820,8 +850,10 @@ function vim.api.nvim_complete_set(index, opts) end --- @return integer function vim.api.nvim_create_augroup(name, opts) end ---- Creates an `autocommand` event handler, defined by `callback` (Lua function ---- or Vimscript function name string) or `command` (Ex command string). +--- 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 @@ -849,39 +881,39 @@ function vim.api.nvim_create_augroup(name, opts) end --- pattern = vim.fn.expand("~") .. "/some/path/*.py" --- ``` --- +--- --- @param event any (string|array) Event(s) that will trigger the handler --- (`callback` or `command`). --- @param 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. Receives a table argument with these keys: ---- • id: (number) autocommand id ---- • event: (string) name of the triggered event ---- `autocmd-events` ---- • group: (number|nil) autocommand group id, if any ---- • match: (string) expanded value of `` ---- • buf: (number) expanded value of `` ---- • file: (string) expanded value of `` ---- • data: (any) arbitrary data passed from ---- `nvim_exec_autocmds()` ---- ---- • 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`. +--- • 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. Receives a +--- table argument with these keys: +--- • id: (number) autocommand id +--- • event: (string) name of the triggered event +--- `autocmd-events` +--- • group: (number|nil) autocommand group id, if any +--- • match: (string) expanded value of `` +--- • buf: (number) expanded value of `` +--- • file: (string) expanded value of `` +--- • data: (any) arbitrary data passed from +--- `nvim_exec_autocmds()` +--- • 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 function vim.api.nvim_create_autocmd(event, opts) end @@ -894,9 +926,11 @@ function vim.api.nvim_create_autocmd(event, opts) end --- @return integer function vim.api.nvim_create_buf(listed, scratch) end ---- Creates a new namespace or gets an existing one. *namespace* +--- Creates a new namespace or gets an existing one. *namespace* +--- --- Namespaces are used for buffer highlights and virtual text, see --- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`. +--- --- Namespaces can be named or anonymous. If `name` matches an existing --- namespace, the associated id is returned. If `name` is an empty string a --- new, anonymous namespace is created. @@ -906,7 +940,9 @@ function vim.api.nvim_create_buf(listed, scratch) end function vim.api.nvim_create_namespace(name) end --- Creates a global `user-commands` command. +--- --- For Lua usage see `lua-guide-commands-create`. +--- --- Example: --- --- ```vim @@ -915,8 +951,9 @@ function vim.api.nvim_create_namespace(name) end --- Hello world! --- ``` --- +--- --- @param name string Name of the new user command. Must begin with an uppercase ---- letter. +--- letter. --- @param command any 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 @@ -943,23 +980,24 @@ function vim.api.nvim_create_namespace(name) end --- Has the same structure as the "mods" key of --- `nvim_parse_cmd()`. --- @param 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` +--- • 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` function vim.api.nvim_create_user_command(name, command, opts) end --- Delete an autocommand group by id. +--- --- To get a group id one can use `nvim_get_autocmds()`. +--- --- NOTE: behavior differs from `:augroup-delete`. When deleting a group, --- autocommands contained in this group will also be deleted and cleared. --- This group will no longer exist. @@ -968,6 +1006,7 @@ function vim.api.nvim_create_user_command(name, command, opts) end function vim.api.nvim_del_augroup_by_id(id) end --- Delete an autocommand group by name. +--- --- NOTE: behavior differs from `:augroup-delete`. When deleting a group, --- autocommands contained in this group will also be deleted and cleared. --- This group will no longer exist. @@ -985,6 +1024,7 @@ function vim.api.nvim_del_autocmd(id) end function vim.api.nvim_del_current_line() end --- Unmaps a global `mapping` for the given mode. +--- --- To unmap a buffer-local mapping, use `nvim_buf_del_keymap()`. --- --- @param mode string @@ -1010,14 +1050,14 @@ function vim.api.nvim_del_var(name) end --- Echo a message. --- --- @param chunks any[] A list of [text, hl_group] arrays, each representing a text ---- chunk with specified highlight. `hl_group` element can be ---- omitted for no highlight. +--- chunk with specified highlight. `hl_group` element can be +--- omitted for no highlight. --- @param history boolean if true, add to `message-history`. --- @param opts vim.api.keyset.echo_opts Optional parameters. ---- • verbose: Message was printed as a result of 'verbose' ---- option if Nvim was invoked with -V3log_file, the message ---- will be redirected to the log_file and suppressed from ---- direct output. +--- • verbose: Message was printed as a result of 'verbose' option +--- if Nvim was invoked with -V3log_file, the message will be +--- redirected to the log_file and suppressed from direct +--- output. function vim.api.nvim_echo(chunks, history, opts) end --- Writes a message to the Vim error buffer. Does not append "\n", the @@ -1034,6 +1074,7 @@ function vim.api.nvim_err_writeln(str) end --- Evaluates a Vimscript `expression`. Dictionaries and Lists are recursively --- expanded. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param expr string Vimscript expression string @@ -1068,8 +1109,10 @@ function vim.api.nvim_exec(src, output) end --- Executes Vimscript (multiline block of Ex commands), like anonymous --- `:source`. +--- --- Unlike `nvim_command()` this function supports heredocs, script-scope --- (s:), etc. +--- --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param src string Vimscript code @@ -1084,24 +1127,27 @@ function vim.api.nvim_exec2(src, opts) end --- --- @param event any (String|Array) The event or events to execute --- @param opts vim.api.keyset.exec_autocmds Dictionary of autocommand options: ---- • group (string|integer) optional: the autocommand group name ---- or id to match against. `autocmd-groups`. ---- • pattern (string|array) optional: defaults to "*" ---- `autocmd-pattern`. Cannot be used with {buffer}. ---- • buffer (integer) optional: buffer number ---- `autocmd-buflocal`. Cannot be used with {pattern}. ---- • modeline (bool) optional: defaults to true. Process the ---- modeline after the autocommands ``. ---- • data (any): arbitrary data to send to the autocommand ---- callback. See `nvim_create_autocmd()` for details. +--- • group (string|integer) optional: the autocommand group name +--- or id to match against. `autocmd-groups`. +--- • pattern (string|array) optional: defaults to "*" +--- `autocmd-pattern`. Cannot be used with {buffer}. +--- • buffer (integer) optional: buffer number `autocmd-buflocal`. +--- Cannot be used with {pattern}. +--- • modeline (bool) optional: defaults to true. Process the +--- modeline after the autocommands ``. +--- • data (any): arbitrary data to send to the autocommand +--- callback. See `nvim_create_autocmd()` for details. function vim.api.nvim_exec_autocmds(event, opts) end --- Sends input-keys to Nvim, subject to various quirks controlled by `mode` --- flags. This is a blocking call, unlike `nvim_input()`. +--- --- On execution error: does not fail, but updates v:errmsg. +--- --- To input sequences like use `nvim_replace_termcodes()` (typically --- with escape_ks=false) to replace `keycodes`, then pass the result to --- nvim_feedkeys(). +--- --- Example: --- --- ```vim @@ -1109,6 +1155,7 @@ function vim.api.nvim_exec_autocmds(event, opts) end --- :call nvim_feedkeys(key, 'n', v:false) --- ``` --- +--- --- @param keys string to be typed --- @param mode string behavior flags, see `feedkeys()` --- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`. This should be @@ -1117,6 +1164,7 @@ function vim.api.nvim_exec_autocmds(event, opts) end function vim.api.nvim_feedkeys(keys, mode, escape_ks) end --- Gets the option information for all options. +--- --- The dictionary has the full option names as keys and option metadata --- dictionaries as detailed at `nvim_get_option_info2()`. --- @@ -1124,6 +1172,7 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end function vim.api.nvim_get_all_options_info() end --- Get all autocommands that match the corresponding {opts}. +--- --- These examples will get autocommands matching ALL the given criteria: --- --- ```lua @@ -1164,6 +1213,7 @@ function vim.api.nvim_get_chan_info(chan) end --- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or --- "#rrggbb" hexadecimal string. +--- --- Example: --- --- ```vim @@ -1171,11 +1221,13 @@ function vim.api.nvim_get_chan_info(chan) end --- :echo nvim_get_color_by_name("#cbcbcb") --- ``` --- +--- --- @param name string Color name or "#rrggbb" string --- @return integer function vim.api.nvim_get_color_by_name(name) end --- Returns a map of color names and RGB values. +--- --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values --- (e.g. 65535). --- @@ -1183,6 +1235,7 @@ function vim.api.nvim_get_color_by_name(name) end function vim.api.nvim_get_color_map() end --- Gets a map of global (non-buffer-local) Ex commands. +--- --- Currently only `user-commands` are supported, not builtin Ex commands. --- --- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false} @@ -1223,12 +1276,12 @@ function vim.api.nvim_get_current_win() end --- `nvim_get_namespaces()`. Use 0 to get global highlight groups --- `:highlight`. --- @param opts vim.api.keyset.get_highlight Options dict: ---- • name: (string) Get a highlight definition by name. ---- • id: (integer) Get a highlight definition by id. ---- • link: (boolean, default true) Show linked group name ---- instead of effective definition `:hi-link`. ---- • create: (boolean, default true) When highlight group ---- doesn't exist create it. +--- • name: (string) Get a highlight definition by name. +--- • id: (integer) Get a highlight definition by id. +--- • link: (boolean, default true) Show linked group name instead +--- of effective definition `:hi-link`. +--- • create: (boolean, default true) When highlight group doesn't +--- exist create it. --- @return vim.api.keyset.hl_info function vim.api.nvim_get_hl(ns_id, opts) end @@ -1245,6 +1298,7 @@ function vim.api.nvim_get_hl_by_id(hl_id, rgb) end function vim.api.nvim_get_hl_by_name(name, rgb) end --- Gets a highlight group by name +--- --- similar to `hlID()`, but allocates a new ID if not present. --- --- @param name string @@ -1270,6 +1324,7 @@ function vim.api.nvim_get_keymap(mode) end --- Returns a `(row, col, buffer, buffername)` tuple representing the position --- of the uppercase/file named mark. "End of line" column position is --- returned as `v:maxcol` (big number). See `mark-motions`. +--- --- Marks are (1,0)-indexed. `api-indexing` --- --- @param name string Mark name @@ -1299,6 +1354,7 @@ function vim.api.nvim_get_option(name) end function vim.api.nvim_get_option_info(name) end --- Gets the option information for one option from arbitrary buffer or window +--- --- Resulting dictionary has keys: --- • name: Name of the option (like 'filetype') --- • shortname: Shortened name of the option (like 'ft') @@ -1360,10 +1416,12 @@ function vim.api.nvim_get_proc(pid) end function vim.api.nvim_get_proc_children(pid) end --- Find files in runtime directories +--- --- "name" can contain wildcards. For example --- nvim_get_runtime_file("colors/*.vim", true) will return all color scheme --- files. Always use forward slashes (/) in the search pattern for --- subdirectories regardless of platform. +--- --- It is not an error to not find any files. An empty array is returned then. --- --- @param name string pattern of files to search for @@ -1386,6 +1444,7 @@ function vim.api.nvim_get_vvar(name) end --- Queues raw user-input. Unlike `nvim_feedkeys()`, this uses a low-level --- input buffer and the call is non-blocking (input is processed --- asynchronously by the eventloop). +--- --- On execution error: does not fail, but updates v:errmsg. --- --- @param keys string to be typed @@ -1393,14 +1452,15 @@ function vim.api.nvim_get_vvar(name) end function vim.api.nvim_input(keys) end --- Send mouse event from GUI. +--- --- Non-blocking: does not wait on any result, but queues the event to be --- processed soon by the event loop. --- --- @param button string Mouse button: one of "left", "right", "middle", "wheel", ---- "move", "x1", "x2". ---- @param action string For ordinary buttons, one of "press", "drag", "release". ---- For the wheel, one of "up", "down", "left", "right". ---- Ignored for "move". +--- "move", "x1", "x2". +--- @param action string For ordinary buttons, one of "press", "drag", "release". For +--- the wheel, one of "up", "down", "left", "right". Ignored for +--- "move". --- @param modifier string String of modifiers each represented by a single char. The --- same specifiers are used as for a key press, except that --- the "-" separator is optional, so "C-A-", "c-a" and "CA" @@ -1411,6 +1471,7 @@ function vim.api.nvim_input(keys) end function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end --- Gets the current list of buffer handles +--- --- Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use --- `nvim_buf_is_loaded()` to check if a buffer is loaded. --- @@ -1449,6 +1510,7 @@ function vim.api.nvim_list_wins() end function vim.api.nvim_load_context(dict) end --- Notify the user with a message +--- --- Relays the call to vim.notify . By default forwards your message in the --- echo area but can be overridden to trigger desktop notifications. --- @@ -1459,10 +1521,12 @@ function vim.api.nvim_load_context(dict) end function vim.api.nvim_notify(msg, log_level, opts) end --- Open a terminal instance in a buffer +--- --- By default (and currently the only option) the terminal will not be --- connected to an external process. Instead, input send on the channel will --- be echoed directly by the terminal. This is useful to display ANSI --- terminal sequences returned as part of a rpc message, or similar. +--- --- Note: to directly initiate the terminal using the right size, display the --- buffer in a configured window before calling this. For instance, for a --- floating display, first create an empty buffer using `nvim_create_buf()`, @@ -1472,27 +1536,30 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- --- @param buffer integer the buffer to use (expected to be empty) --- @param opts vim.api.keyset.open_term Optional parameters. ---- • on_input: Lua callback for input sent, i e keypresses in ---- terminal mode. Note: keypresses are sent raw as they would ---- be to the pty master end. For instance, a carriage return ---- is sent as a "\r", not as a "\n". `textlock` applies. It ---- is possible to call `nvim_chan_send()` directly in the ---- callback however. ["input", term, bufnr, data] ---- • force_crlf: (boolean, default true) Convert "\n" to ---- "\r\n". +--- • on_input: Lua callback for input sent, i e keypresses in +--- terminal mode. Note: keypresses are sent raw as they would +--- be to the pty master end. For instance, a carriage return is +--- sent as a "\r", not as a "\n". `textlock` applies. It is +--- possible to call `nvim_chan_send()` directly in the callback +--- however. ["input", term, bufnr, data] +--- • force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- @return integer function vim.api.nvim_open_term(buffer, opts) end --- Opens a new split window, or a floating window if `relative` is specified, --- or an external window (managed by the UI) if `external` is specified. +--- --- Floats are windows that are drawn above the split layout, at some anchor --- position in some other window. Floats can be drawn internally or by --- external GUI with the `ui-multigrid` extension. External windows are only --- supported with multigrid GUIs, and are displayed as separate top-level --- windows. +--- --- For a general overview of floats, see `api-floatwin`. +--- --- The `width` and `height` of the new window must be specified when opening --- a floating window, but are optional for normal windows. +--- --- If `relative` and `external` are omitted, a normal "split" window is --- created. The `win` property determines which window will be split. If no --- `win` is provided or `win == 0`, a window will be created adjacent to the @@ -1501,15 +1568,18 @@ function vim.api.nvim_open_term(buffer, opts) end --- control split direction. For `vertical`, the exact direction is determined --- by `'splitright'` and `'splitbelow'`. Split windows cannot have --- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. +--- --- With relative=editor (row=0,col=0) refers to the top-left corner of the --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right --- corner. Fractional values are allowed, but the builtin implementation --- (used by non-multigrid UIs) will always round down to nearest integer. +--- --- Out-of-bounds values, and configurations that make the float not fit --- inside the main editor, are allowed. The builtin implementation truncates --- values so floats are fully within the main screen grid. External GUIs --- could let floats hover outside of the main window like a tooltip, but this --- should not be used to specify arbitrary WM screen positions. +--- --- Example (Lua): window-relative float --- --- ```lua @@ -1533,6 +1603,7 @@ function vim.api.nvim_open_term(buffer, opts) end --- }) --- ``` --- +--- --- @param buffer integer Buffer to display, or 0 for current buffer --- @param enter boolean Enter the window (make it the current window) --- @param config vim.api.keyset.win_config Map defining the window configuration. Keys: @@ -1543,7 +1614,6 @@ function vim.api.nvim_open_term(buffer, opts) end --- window. --- • "cursor" Cursor position in current window. --- • "mouse" Mouse position ---- --- • win: `window-ID` window to split, or relative window when --- creating a float (relative="win"). --- • anchor: Decides which corner of the float to place at @@ -1552,17 +1622,15 @@ function vim.api.nvim_open_term(buffer, opts) end --- • "NE" northeast --- • "SW" southwest --- • "SE" southeast ---- --- • width: Window width (in character cells). Minimum of 1. --- • height: Window height (in character cells). Minimum of 1. --- • bufpos: Places float relative to buffer text (only when --- relative="win"). Takes a tuple of zero-indexed [line, ---- column]. `row` and `col` if given are ---- applied relative to this position, else they default to: +--- column]. `row` and `col` if given are applied relative to +--- this position, else they default to: --- • `row=1` and `col=0` if `anchor` is "NW" or "NE" --- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus --- like a tooltip near the buffer text). ---- --- • row: Row position in units of "screen cell height", may be --- fractional. --- • col: Column position in units of "screen cell width", may @@ -1583,7 +1651,6 @@ function vim.api.nvim_open_term(buffer, opts) end --- wildoptions+=pum) The default value for floats are 50. --- In general, values below 100 are recommended, unless --- there is a good reason to overshadow builtin elements. ---- --- • style: (optional) Configure the appearance of the window. --- Currently only supports one value: --- • "minimal" Nvim will display the window with many UI @@ -1596,14 +1663,13 @@ function vim.api.nvim_open_term(buffer, opts) end --- empty. The end-of-buffer region is hidden by setting --- `eob` flag of 'fillchars' to a space char, and clearing --- the `hl-EndOfBuffer` region in 'winhighlight'. ---- --- • border: Style of (optional) window border. This can either --- be a string or an array. The string values are --- • "none": No border (default). --- • "single": A single line box. --- • "double": A double line box. ---- • "rounded": Like "single", but with rounded corners ("╭" ---- etc.). +--- • "rounded": Like "single", but with rounded corners +--- ("╭" etc.). --- • "solid": Adds padding by a single whitespace cell. --- • "shadow": A drop shadow effect by blending with the --- background. @@ -1611,18 +1677,35 @@ function vim.api.nvim_open_term(buffer, opts) end --- any divisor of eight. The array will specify the eight --- chars building up the border in a clockwise fashion --- starting with the top-left corner. As an example, the ---- double box style could be specified as [ "╔", "═" ,"╗", ---- "║", "╝", "═", "╚", "║" ]. If the number of chars are ---- less than eight, they will be repeated. Thus an ASCII ---- border could be specified as [ "/", "-", "\\", "|" ], or ---- all chars the same as [ "x" ]. An empty string can be ---- used to turn off a specific border, for instance, [ "", ---- "", "", ">", "", "", "", "<" ] will only make vertical ---- borders but not horizontal ones. By default, ---- `FloatBorder` highlight is used, which links to ---- `WinSeparator` when not defined. It could also be ---- specified by character: [ ["+", "MyCorner"], ["x", ---- "MyBorder"] ]. +--- double box style could be specified as: +--- ``` +--- [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. +--- ``` +--- +--- If the number of chars are less than eight, they will be +--- repeated. Thus an ASCII border could be specified as +--- ``` +--- [ "/", "-", \"\\\\\", "|" ], +--- ``` +--- +--- or all chars the same as +--- ``` +--- [ "x" ]. +--- ``` +--- +--- An empty string can be used to turn off a specific border, +--- for instance, +--- ``` +--- [ "", "", "", ">", "", "", "", "<" ] +--- ``` +--- +--- will only make vertical borders but not horizontal ones. +--- By default, `FloatBorder` highlight is used, which links +--- to `WinSeparator` when not defined. It could also be +--- specified by character: +--- ``` +--- [ ["+", "MyCorner"], ["x", "MyBorder"] ]. +--- ``` --- --- • title: Title (optional) in window border, string or list. --- List should consist of `[text, highlight]` tuples. If @@ -1654,6 +1737,7 @@ function vim.api.nvim_open_win(buffer, enter, config) end function vim.api.nvim_out_write(str) end --- Parse command line. +--- --- Doesn't check the validity of command arguments. --- --- @param str string Command line string to parse. Cannot contain "\n". @@ -1665,17 +1749,17 @@ function vim.api.nvim_parse_cmd(str, opts) end --- --- @param expr string Expression to parse. Always treated as a single line. --- @param flags string Flags: ---- • "m" if multiple expressions in a row are allowed (only ---- the first one will be parsed), ---- • "E" if EOC tokens are not allowed (determines whether ---- they will stop parsing process or be recognized as an ---- operator/space, though also yielding an error). ---- • "l" when needing to start parsing with lvalues for ---- ":let" or ":for". Common flag sets: ---- • "m" to parse like for ":echo". ---- • "E" to parse like for "=". ---- • empty string for ":call". ---- • "lm" to parse for ":let". +--- • "m" if multiple expressions in a row are allowed (only the +--- first one will be parsed), +--- • "E" if EOC tokens are not allowed (determines whether they +--- will stop parsing process or be recognized as an +--- operator/space, though also yielding an error). +--- • "l" when needing to start parsing with lvalues for ":let" +--- or ":for". Common flag sets: +--- • "m" to parse like for ":echo". +--- • "E" to parse like for "=". +--- • empty string for ":call". +--- • "lm" to parse for ":let". --- @param highlight boolean If true, return value will also include "highlight" key --- containing array of 4-tuples (arrays) (Integer, Integer, --- Integer, String), where first three numbers define the @@ -1686,8 +1770,10 @@ function vim.api.nvim_parse_cmd(str, opts) end function vim.api.nvim_parse_expression(expr, flags, highlight) end --- Pastes at cursor, in any mode. +--- --- Invokes the `vim.paste` handler, which handles each mode appropriately. --- Sets redo/undo. Faster than `nvim_input()`. Lines break at LF ("\n"). +--- --- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err` --- but do not affect the return value (which is strictly decided by --- `vim.paste()`). On error, subsequent calls are ignored ("drained") until @@ -1696,8 +1782,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- @param data string Multiline input. May be binary (containing NUL bytes). --- @param crlf boolean Also break lines at CR and CRLF. --- @param phase integer -1: paste in a single call (i.e. without streaming). To ---- "stream" a paste, call `nvim_paste` sequentially ---- with these `phase` values: +--- "stream" a paste, call `nvim_paste` sequentially with these +--- `phase` values: --- • 1: starts the paste (exactly once) --- • 2: continues the paste (zero or more times) --- • 3: ends the paste (exactly once) @@ -1705,16 +1791,16 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end function vim.api.nvim_paste(data, crlf, phase) end --- Puts text at cursor, in any mode. +--- --- Compare `:put` and `p` which are always linewise. --- --- @param lines string[] `readfile()`-style list of lines. `channel-lines` --- @param type string Edit behavior: any `getregtype()` result, or: ---- • "b" `blockwise-visual` mode (may include width, e.g. "b3") ---- • "c" `charwise` mode ---- • "l" `linewise` mode ---- • "" guess by contents, see `setreg()` ---- @param after boolean If true insert after cursor (like `p`), or before (like ---- `P`). +--- • "b" `blockwise-visual` mode (may include width, e.g. "b3") +--- • "c" `charwise` mode +--- • "l" `linewise` mode +--- • "" guess by contents, see `setreg()` +--- @param after boolean If true insert after cursor (like `p`), or before (like `P`). --- @param follow boolean If true place cursor at end of inserted text. function vim.api.nvim_put(lines, type, after, follow) end @@ -1729,14 +1815,15 @@ function vim.api.nvim_put(lines, type, after, follow) end function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end --- Selects an item in the completion popup menu. +--- --- If neither `ins-completion` nor `cmdline-completion` popup menu is active --- this API call is silently ignored. Useful for an external UI using --- `ui-popupmenu` to control the popup menu with the mouse. Can also be used --- in a mapping; use `:map-cmd` or a Lua mapping to ensure the mapping --- doesn't end completion mode. --- ---- @param item integer Index (zero-based) of the item to select. Value of -1 ---- selects nothing and restores the original text. +--- @param item integer Index (zero-based) of the item to select. Value of -1 selects +--- nothing and restores the original text. --- @param insert boolean For `ins-completion`, whether the selection should be --- inserted in the buffer. Ignored for `cmdline-completion`. --- @param finish boolean Finish the completion and dismiss the popup menu. Implies @@ -1770,13 +1857,16 @@ function vim.api.nvim_set_current_tabpage(tabpage) end function vim.api.nvim_set_current_win(window) end --- Set or change decoration provider for a `namespace` +--- --- This is a very general purpose interface for having Lua callbacks being --- triggered during the redraw code. +--- --- The expected usage is to set `extmarks` for the currently redrawn buffer. --- `nvim_buf_set_extmark()` can be called to add marks on a per-window or --- per-lines basis. Use the `ephemeral` key to only use the mark for the --- current screen redraw (the callback will be called again for the next --- redraw). +--- --- Note: this function should not be called often. Rather, the callbacks --- themselves can be used to throttle unneeded callbacks. the `on_start` --- callback can return `false` to disable the provider until the next redraw. @@ -1785,26 +1875,27 @@ function vim.api.nvim_set_current_win(window) end --- plugin managing multiple sources of decoration should ideally only set one --- provider, and merge the sources internally. You can use multiple `ns_id` --- for the extmarks set/modified inside the callback anyway. +--- --- Note: doing anything other than setting extmarks is considered --- experimental. Doing things like changing options are not explicitly --- forbidden, but is likely to have unexpected consequences (such as 100% CPU --- consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is --- quite dubious for the moment. +--- --- Note: It is not allowed to remove or update extmarks in 'on_line' --- callbacks. --- --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks: ---- • on_start: called first on each screen redraw ["start", ---- tick] ---- • on_buf: called for each buffer being redrawn (before window ---- callbacks) ["buf", bufnr, tick] ---- • on_win: called when starting to redraw a specific window. ---- ["win", winid, bufnr, topline, botline] ---- • on_line: called for each buffer line being redrawn. (The ---- interaction with fold lines is subject to change) ["line", ---- winid, bufnr, row] ---- • on_end: called at the end of a redraw cycle ["end", tick] +--- • on_start: called first on each screen redraw ["start", tick] +--- • on_buf: called for each buffer being redrawn (before window +--- callbacks) ["buf", bufnr, tick] +--- • on_win: called when starting to redraw a specific window. +--- ["win", winid, bufnr, topline, botline] +--- • on_line: called for each buffer line being redrawn. (The +--- interaction with fold lines is subject to change) ["line", +--- winid, bufnr, row] +--- • on_end: called at the end of a redraw cycle ["end", tick] function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- Sets a highlight group. @@ -1816,31 +1907,31 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- activate them. --- @param name string Highlight group name, e.g. "ErrorMsg" --- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys: ---- • fg: color name or "#RRGGBB", see note. ---- • bg: color name or "#RRGGBB", see note. ---- • sp: color name or "#RRGGBB" ---- • blend: integer between 0 and 100 ---- • bold: boolean ---- • standout: boolean ---- • underline: boolean ---- • undercurl: boolean ---- • underdouble: boolean ---- • underdotted: boolean ---- • underdashed: boolean ---- • strikethrough: boolean ---- • italic: boolean ---- • reverse: boolean ---- • nocombine: boolean ---- • link: name of another highlight group to link to, see ---- `:hi-link`. ---- • default: Don't override existing definition `:hi-default` ---- • ctermfg: Sets foreground of cterm color `ctermfg` ---- • ctermbg: Sets background of cterm color `ctermbg` ---- • cterm: cterm attribute map, like `highlight-args`. If not ---- set, cterm attributes will match those from the attribute ---- map documented above. ---- • force: if true force update the highlight group when it ---- exists. +--- • fg: color name or "#RRGGBB", see note. +--- • bg: color name or "#RRGGBB", see note. +--- • sp: color name or "#RRGGBB" +--- • blend: integer between 0 and 100 +--- • bold: boolean +--- • standout: boolean +--- • underline: boolean +--- • undercurl: boolean +--- • underdouble: boolean +--- • underdotted: boolean +--- • underdashed: boolean +--- • strikethrough: boolean +--- • italic: boolean +--- • reverse: boolean +--- • nocombine: boolean +--- • link: name of another highlight group to link to, see +--- `:hi-link`. +--- • default: Don't override existing definition `:hi-default` +--- • ctermfg: Sets foreground of cterm color `ctermfg` +--- • ctermbg: Sets background of cterm color `ctermbg` +--- • cterm: cterm attribute map, like `highlight-args`. If not +--- set, cterm attributes will match those from the attribute map +--- documented above. +--- • force: if true force update the highlight group when it +--- exists. function vim.api.nvim_set_hl(ns_id, name, val) end --- Set active namespace for highlights defined with `nvim_set_hl()`. This can @@ -1851,6 +1942,7 @@ function vim.api.nvim_set_hl_ns(ns_id) end --- Set active namespace for highlights defined with `nvim_set_hl()` while --- redrawing. +--- --- This function meant to be called while redrawing, primarily from --- `nvim_set_decoration_provider()` on_win and on_line callbacks, which are --- allowed to change the namespace during a redraw cycle. @@ -1859,9 +1951,12 @@ function vim.api.nvim_set_hl_ns(ns_id) end function vim.api.nvim_set_hl_ns_fast(ns_id) end --- Sets a global `mapping` for the given mode. +--- --- To set a buffer-local mapping, use `nvim_buf_set_keymap()`. +--- --- Unlike `:map`, leading/trailing whitespace is accepted as part of the --- {lhs} or {rhs}. Empty {rhs} is ``. `keycodes` are replaced as usual. +--- --- Example: --- --- ```vim @@ -1874,8 +1969,9 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- nmap --- ``` --- ---- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …) or ---- "!" for `:map!`, or empty string for `:map`. "ia", "ca" or +--- +--- @param mode string Mode short-name (map command prefix: "n", "i", "v", "x", …) +--- or "!" for `:map!`, or empty string for `:map`. "ia", "ca" or --- "!a" for abbreviation in Insert mode, Cmdline mode, or both, --- respectively --- @param lhs string Left-hand-side `{lhs}` of the mapping. @@ -1899,15 +1995,16 @@ function vim.api.nvim_set_option(name, value) end --- 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. --- --- @param name string Option name --- @param value any New option value --- @param 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. +--- • 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. function vim.api.nvim_set_option_value(name, value, opts) end --- Sets a global (g:) variable. @@ -1990,7 +2087,7 @@ function vim.api.nvim_win_add_ns(window, ns_id) end --- --- @param window integer Window handle, or 0 for current window --- @param fun function Function to call inside the window (currently Lua callable ---- only) +--- only) --- @return any function vim.api.nvim_win_call(window, fun) end @@ -1998,8 +2095,8 @@ function vim.api.nvim_win_call(window, fun) end --- --- @param window integer Window handle, or 0 for current window --- @param 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. +--- unwritten changes can be closed. The buffer will become +--- hidden, even if 'hidden' is not set. function vim.api.nvim_win_close(window, force) end --- Removes a window-scoped (w:) variable @@ -2015,7 +2112,9 @@ function vim.api.nvim_win_del_var(window, name) end function vim.api.nvim_win_get_buf(window) end --- Gets window configuration. +--- --- The returned value may be given to `nvim_open_win()`. +--- --- `relative` is empty for normal windows. --- --- @param window integer Window handle, or 0 for current window @@ -2081,6 +2180,7 @@ function vim.api.nvim_win_get_width(window) end --- 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. @@ -2109,6 +2209,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- Configures window layout. Currently only for floating and external windows --- (including changing a split window to those layouts). +--- --- When reconfiguring a floating window, absent option keys will not be --- changed. `row`/`col` and `relative` must be reconfigured together. --- @@ -2132,6 +2233,7 @@ function vim.api.nvim_win_set_height(window, height) end --- 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. --- --- @param window integer @@ -2160,23 +2262,26 @@ function vim.api.nvim_win_set_width(window, width) end --- 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()`. --- --- @param window integer Window handle, or 0 for current window. --- @param 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 ---- omitted include the whole line. +--- • 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 omitted +--- include the whole line. --- @return table function vim.api.nvim_win_text_height(window, opts) end diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index a422a65792..472162ecc1 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -3,65 +3,63 @@ error('Cannot require a meta file') ----@defgroup vim.builtin ---- ----@brief 
help
----vim.api.{func}({...})                                                    *vim.api*
----    Invokes Nvim |API| function {func} with arguments {...}.
----    Example: call the "nvim_get_current_line()" API function: >lua
----        print(tostring(vim.api.nvim_get_current_line()))
----
----vim.NIL                                                                  *vim.NIL*
----    Special value representing NIL in |RPC| and |v:null| in Vimscript
----    conversion, and similar cases. Lua `nil` cannot be used as part of a Lua
----    table representing a Dictionary or Array, because it is treated as
----    missing: `{"foo", nil}` is the same as `{"foo"}`.
----
----vim.type_idx                                                        *vim.type_idx*
----    Type index for use in |lua-special-tbl|. Specifying one of the values from
----    |vim.types| allows typing the empty table (it is unclear whether empty Lua
----    table represents empty list or empty array) and forcing integral numbers
----    to be |Float|. See |lua-special-tbl| for more details.
----
----vim.val_idx                                                          *vim.val_idx*
----    Value index for tables representing |Float|s. A table representing
----    floating-point value 1.0 looks like this: >lua
----        {
----          [vim.type_idx] = vim.types.float,
----          [vim.val_idx] = 1.0,
----        }
----<    See also |vim.type_idx| and |lua-special-tbl|.
----
----vim.types                                                              *vim.types*
----    Table with possible values for |vim.type_idx|. Contains two sets of
----    key-value pairs: first maps possible values for |vim.type_idx| to
----    human-readable strings, second maps human-readable type names to values
----    for |vim.type_idx|. Currently contains pairs for `float`, `array` and
----        `dictionary` types.
----
----    Note: One must expect that values corresponding to `vim.types.float`,
----    `vim.types.array` and `vim.types.dictionary` fall under only two following
----    assumptions:
----    1. Value may serve both as a key and as a value in a table. Given the
----       properties of Lua tables this basically means “value is not `nil`”.
----    2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the
----       same as `value`.
----    No other restrictions are put on types, and it is not guaranteed that
----    values corresponding to `vim.types.float`, `vim.types.array` and
----    `vim.types.dictionary` will not change or that `vim.types` table will only
----    contain values for these three types.
----
----                                                   *log_levels* *vim.log.levels*
----Log levels are one of the values defined in `vim.log.levels`:
----
----    vim.log.levels.DEBUG
----    vim.log.levels.ERROR
----    vim.log.levels.INFO
----    vim.log.levels.TRACE
----    vim.log.levels.WARN
----    vim.log.levels.OFF
----
----
+--- @brief 
help
+--- vim.api.{func}({...})                                                    *vim.api*
+---     Invokes Nvim |API| function {func} with arguments {...}.
+---     Example: call the "nvim_get_current_line()" API function: >lua
+---         print(tostring(vim.api.nvim_get_current_line()))
+---
+--- vim.NIL                                                                  *vim.NIL*
+---     Special value representing NIL in |RPC| and |v:null| in Vimscript
+---     conversion, and similar cases. Lua `nil` cannot be used as part of a Lua
+---     table representing a Dictionary or Array, because it is treated as
+---     missing: `{"foo", nil}` is the same as `{"foo"}`.
+---
+--- vim.type_idx                                                        *vim.type_idx*
+---     Type index for use in |lua-special-tbl|. Specifying one of the values from
+---     |vim.types| allows typing the empty table (it is unclear whether empty Lua
+---     table represents empty list or empty array) and forcing integral numbers
+---     to be |Float|. See |lua-special-tbl| for more details.
+---
+--- vim.val_idx                                                          *vim.val_idx*
+---     Value index for tables representing |Float|s. A table representing
+---     floating-point value 1.0 looks like this: >lua
+---         {
+---           [vim.type_idx] = vim.types.float,
+---           [vim.val_idx] = 1.0,
+---         }
+--- <    See also |vim.type_idx| and |lua-special-tbl|.
+---
+--- vim.types                                                              *vim.types*
+---     Table with possible values for |vim.type_idx|. Contains two sets of
+---     key-value pairs: first maps possible values for |vim.type_idx| to
+---     human-readable strings, second maps human-readable type names to values
+---     for |vim.type_idx|. Currently contains pairs for `float`, `array` and
+---         `dictionary` types.
+---
+---     Note: One must expect that values corresponding to `vim.types.float`,
+---     `vim.types.array` and `vim.types.dictionary` fall under only two following
+---     assumptions:
+---     1. Value may serve both as a key and as a value in a table. Given the
+---        properties of Lua tables this basically means “value is not `nil`”.
+---     2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the
+---        same as `value`.
+---     No other restrictions are put on types, and it is not guaranteed that
+---     values corresponding to `vim.types.float`, `vim.types.array` and
+---     `vim.types.dictionary` will not change or that `vim.types` table will only
+---     contain values for these three types.
+---
+---                                                    *log_levels* *vim.log.levels*
+--- Log levels are one of the values defined in `vim.log.levels`:
+---
+---     vim.log.levels.DEBUG
+---     vim.log.levels.ERROR
+---     vim.log.levels.INFO
+---     vim.log.levels.TRACE
+---     vim.log.levels.WARN
+---     vim.log.levels.OFF
+---
+---
---@class vim.NIL diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua index e010086615..07d89aafc8 100644 --- a/runtime/lua/vim/_meta/json.lua +++ b/runtime/lua/vim/_meta/json.lua @@ -5,7 +5,7 @@ vim.json = {} -- luacheck: no unused args ----@defgroup vim.json +---@brief --- --- This module provides encoding and decoding of Lua objects to and --- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 5bd502a7c8..f2239e5e5a 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -5,22 +5,20 @@ error('Cannot require a meta file') -- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) -- with types being renamed to include the vim namespace and with some descriptions made less verbose. ----@defgroup vim.lpeg ----
help
----LPeg is a pattern-matching library for Lua, based on
----Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+--- @brief 
help
+--- LPeg is a pattern-matching library for Lua, based on
+--- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
 ---
----                                                                    *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/).
+---                                                                     *lua-lpeg*
+---                                                             *vim.lpeg.Pattern*
+--- The LPeg library for parsing expression grammars is included as `vim.lpeg`
+--- (https://www.inf.puc-rio.br/~roberto/lpeg/).
 ---
----In addition, its regex-like interface is available as |vim.re|
----(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+--- In addition, its regex-like interface is available as |vim.re|
+--- (https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
 ---
----

+---
---- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs). vim.lpeg = {} --- @class vim.lpeg.Pattern @@ -88,6 +86,7 @@ function Pattern:match(subject, init) end --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`. --- +--- @param value vim.lpeg.Pattern|string|integer|boolean|table|function --- @return "pattern"|nil function vim.lpeg.type(value) end diff --git a/runtime/lua/vim/_meta/mpack.lua b/runtime/lua/vim/_meta/mpack.lua index 54e097ad97..3970341b78 100644 --- a/runtime/lua/vim/_meta/mpack.lua +++ b/runtime/lua/vim/_meta/mpack.lua @@ -2,14 +2,17 @@ -- luacheck: no unused args ---- @defgroup vim.mpack +--- @brief --- --- This module provides encoding and decoding of Lua objects to and --- from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. --- Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. --- @param str string +--- @return any function vim.mpack.decode(str) end --- Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. +--- @param obj any +--- @return string function vim.mpack.encode(obj) end diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua index 4f254b19a0..14c94c7824 100644 --- a/runtime/lua/vim/_meta/re.lua +++ b/runtime/lua/vim/_meta/re.lua @@ -7,15 +7,12 @@ error('Cannot require a meta file') -- Copyright © 2007-2023 Lua.org, PUC-Rio. -- See 'lpeg.html' for license ---- @defgroup vim.re ----
help
----The `vim.re` module provides a conventional regex-like syntax for pattern usage
----within LPeg |vim.lpeg|.
+--- @brief
+--- The `vim.re` module provides a conventional regex-like syntax for pattern usage
+--- within LPeg |vim.lpeg|.
 ---
----See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
----documentation including regex syntax and more concrete examples.
----
----
+--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original +--- documentation including regex syntax and more concrete examples. --- 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 diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua index 58aa2be8c2..ab403b97e7 100644 --- a/runtime/lua/vim/_meta/regex.lua +++ b/runtime/lua/vim/_meta/regex.lua @@ -2,8 +2,6 @@ -- luacheck: no unused args ---- @defgroup vim.regex ---- --- @brief Vim regexes can be used directly from Lua. Currently they only allow --- matching within a single line. -- cgit From cb146cc4aad746053535533cbea8834414ea82a2 Mon Sep 17 00:00:00 2001 From: Maria José Solano Date: Fri, 9 Feb 2024 10:35:13 -0800 Subject: docs(lpeg): merge upstream changes --- runtime/lua/vim/_meta/lpeg.lua | 70 +++++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 35 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index f2239e5e5a..fef07d3046 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -2,7 +2,7 @@ error('Cannot require a meta file') -- These types were taken from https://github.com/LuaCATS/lpeg --- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) +-- (based on revision e6789e28e5b91a4a277a2a03081d708c403a3e34) -- with types being renamed to include the vim namespace and with some descriptions made less verbose. --- @brief 
help
@@ -49,10 +49,10 @@ local Pattern = {}
 --- 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 pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
+--- assert(lpeg.match(pattern, 'hello') == 6)
+--- assert(pattern:match('1 hello') == nil)
 --- ```
 ---
 --- @param pattern vim.lpeg.Pattern
@@ -73,10 +73,10 @@ function vim.lpeg.match(pattern, subject, init) end
 --- 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 pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
+--- assert(lpeg.match(pattern, 'hello') == 6)
+--- assert(pattern:match('1 hello') == nil)
 --- ```
 ---
 --- @param subject string
@@ -103,7 +103,7 @@ function vim.lpeg.version() end
 --- @param max integer
 function vim.lpeg.setmaxstack(max) end
 
---- Converts the given value into a proper pattern. This following rules are applied:
+--- 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.
@@ -113,7 +113,7 @@ function vim.lpeg.setmaxstack(max) end
 --- * 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 captureover the empty string.
+--- * If the argument is a function, returns a pattern equivalent to a match-time capture over the empty string.
 ---
 --- @param value vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @return vim.lpeg.Pattern
@@ -121,7 +121,7 @@ function vim.lpeg.P(value) end
 
 --- 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.
+--- Like the `and` predicate, this pattern never consumes any input, independently of success or failure.
 ---
 --- @param pattern vim.lpeg.Pattern
 --- @return vim.lpeg.Pattern
@@ -129,14 +129,14 @@ function vim.lpeg.B(pattern) end
 
 --- 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.
+--- `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)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
 --- ```
 ---
 --- @param ... string
@@ -144,9 +144,9 @@ function vim.lpeg.B(pattern) end
 function vim.lpeg.R(...) end
 
 --- 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
+--- 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.
+--- `lpeg.R(s..s)`. Note also that both ``lpeg.S('')`` and `lpeg.R()` are patterns that always fail.
 ---
 --- @param string string
 --- @return vim.lpeg.Pattern
@@ -158,7 +158,7 @@ function vim.lpeg.S(string) end
 --- Example:
 ---
 --- ```lua
---- local b = lpeg.P({"(" * ((1 - lpeg.S "()") + lpeg.V(1)) ^ 0 * ")"})
+--- local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'})
 --- assert(b:match('((string))') == 11)
 --- assert(b:match('(') == nil)
 --- ```
@@ -191,12 +191,12 @@ function vim.lpeg.V(v) end
 ---
 --- ```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")
+--- 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')
@@ -216,8 +216,8 @@ function vim.lpeg.locale(tab) end
 --- ```lua
 --- local function split (s, sep)
 ---   sep = lpeg.P(sep)
----   local elem = lpeg.C((1 - sep)^0)
----   local p = elem * (sep * elem)^0
+---   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', ',')
@@ -265,11 +265,11 @@ function vim.lpeg.Cc(...) end
 --- Example:
 ---
 --- ```lua
---- local number = lpeg.R("09") ^ 1 / tonumber
---- local list = number * ("," * number) ^ 0
+--- 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)
+--- assert(sum:match('10,30,43') == 83)
 --- ```
 ---
 --- @param patt vim.lpeg.Pattern
@@ -294,7 +294,7 @@ function vim.lpeg.Cg(patt, name) end
 --- ```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!")
+--- local match_start, match_end = anywhere('world'):match('hello world!')
 --- assert(match_start == 7)
 --- assert(match_end == 12)
 --- ```
@@ -313,7 +313,7 @@ function vim.lpeg.Cp() end
 --- ```lua
 --- local function gsub (s, patt, repl)
 ---   patt = lpeg.P(patt)
----   patt = lpeg.Cs((patt / repl + 1)^0)
+---   patt = lpeg.Cs((patt / repl + 1) ^ 0)
 ---   return lpeg.match(patt, s)
 --- end
 --- assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!')
@@ -337,9 +337,9 @@ function vim.lpeg.Ct(patt) end
 --- 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.
+--- 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.
 ---
 --- @param patt vim.lpeg.Pattern
-- 
cgit 


From f912030d4ed0998b3de90bad9f1b416fffff49c9 Mon Sep 17 00:00:00 2001
From: Maria José Solano 
Date: Wed, 28 Feb 2024 14:14:49 -0800
Subject: docs(lpeg): remove double backticks from meta (#27659)

---
 runtime/lua/vim/_meta/lpeg.lua | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index fef07d3046..202c99f18c 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -129,8 +129,8 @@ function vim.lpeg.B(pattern) end
 
 --- 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.
+--- `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:
 ---
@@ -144,9 +144,9 @@ function vim.lpeg.B(pattern) end
 function vim.lpeg.R(...) end
 
 --- 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
+--- 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.
+--- `lpeg.R(s..s)`. Note also that both `lpeg.S('')` and `lpeg.R()` are patterns that always fail.
 ---
 --- @param string string
 --- @return vim.lpeg.Pattern
-- 
cgit 


From ce7c51a1a3b2b38cdba730aeb53840d0ace32173 Mon Sep 17 00:00:00 2001
From: zeertzjq 
Date: Thu, 29 Feb 2024 07:19:26 +0800
Subject: vim-patch:9.1.0142: getregion() can be improved (#27662)

Problem:  getregion() can be improved (after v9.1.120)
Solution: change getregion() implementation to use pos as lists and
          one optional {opt} dictionary (Shougo Matsushita)

Note: The following is a breaking change!

Currently, the getregion() function (included as of patch v9.1.120) takes
3 arguments: the first 2 arguments are strings, describing a position,
arg3 is the type string.

However, that is slightly inflexible, there is no way to specify
additional arguments. So let's instead change the function signature to:

getregion(pos1, pos2 [, {Dict}]) where both pos1 and pos2 are lists.
This is slightly cleaner, and gives us the flexibility to specify
additional arguments as key/value pairs to the optional Dict arg.

Now it supports the "type" key to specify the selection type
(characterwise, blockwise or linewise) and now in addition one can also
define the selection type, independently of what the 'selection' option
actually is.

Technically, this is a breaking change, but since the getregion()
Vimscript function is still quite new, this should be fine.

closes: vim/vim#14090

https://github.com/vim/vim/commit/19b718828d8d5fab52d94c6cdba694641879ab38

Co-authored-by: Shougo Matsushita 
---
 runtime/lua/vim/_meta/vimfn.lua | 42 ++++++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 17 deletions(-)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 779016f2d1..be89c7dd01 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3525,13 +3525,24 @@ function vim.fn.getreg(regname, list) end
 --- @return table
 function vim.fn.getreginfo(regname) end
 
---- Returns the list of strings from {pos1} to {pos2} as if it's
---- selected in visual mode of {type}.
---- For possible values of {pos1} and {pos2} see |line()|.
---- {type} is the selection type:
----   "v" for |charwise| mode
----   "V" for |linewise| mode
----   "" for |blockwise-visual| mode
+--- Returns the list of strings from {pos1} to {pos2} in current
+--- buffer.
+---
+--- {pos1} and {pos2} must both be |List|s with four numbers.
+--- See |getpos()| for the format of the list.
+---
+--- The optional argument {opts} is a Dict and supports the
+--- following items:
+---
+---   type    Specify the selection type
+---       (default: "v"):
+---       "v"    for |charwise| mode
+---       "V"    for |linewise| mode
+---       ""  for |blockwise-visual| mode
+---
+---   exclusive  If |TRUE|, use exclusive selection
+---       for the end position 'selection'.
+---
 --- You can get the last selection type by |visualmode()|.
 --- If Visual mode is active, use |mode()| to get the Visual mode
 --- (e.g., in a |:vmap|).
@@ -3549,23 +3560,20 @@ function vim.fn.getreginfo(regname) end
 --- - If the selection starts or ends in the middle of a multibyte
 ---   character, it is not included but its selected part is
 ---   substituted with spaces.
---- - If {pos1} or {pos2} equals "v" (see |line()|) and it is not in
----   |visual-mode|, an empty list is returned.
---- - If {pos1}, {pos2} or {type} is an invalid string, an empty
----   list is returned.
---- - If {pos1} or {pos2} is a mark in different buffer, an empty
+--- - If {pos1} or {pos2} is not current in the buffer, an empty
 ---   list is returned.
 ---
 --- Examples: >
 ---   :xnoremap 
----   \ echom getregion('v', '.', mode())
+---   \ echom getregion(
+---   \ getpos('v'), getpos('.'), #{ type: mode() })
 --- <
 ---
---- @param pos1 string
---- @param pos2 string
---- @param type string
+--- @param pos1 table
+--- @param pos2 table
+--- @param opts? table
 --- @return string[]
-function vim.fn.getregion(pos1, pos2, type) end
+function vim.fn.getregion(pos1, pos2, opts) end
 
 --- The result is a String, which is type of register {regname}.
 --- The value will be one of:
-- 
cgit 


From 6ab0876f51e8ff5debdff03b36508fe7279032b7 Mon Sep 17 00:00:00 2001
From: glepnir 
Date: Thu, 29 Feb 2024 19:39:11 +0800
Subject: docs(eval): getline and indent function support string type

Problem: getline and indent function missing string type in param.

Solution: add string type in eval gen.
---
 runtime/lua/vim/_meta/vimfn.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index be89c7dd01..fa13c36a11 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3185,7 +3185,7 @@ function vim.fn.getjumplist(winnr, tabnr) end
 --- 
Date: Sat, 2 Mar 2024 06:42:39 +0800
Subject: vim-patch:87410ab3f556 (#27696)

runtime(doc): some improvements to getregion() docs (vim/vim#14122)

- Mention the default selection behavior
- Remove useless sentence
- Correct description about space padding

https://github.com/vim/vim/commit/87410ab3f556121dfb3b30515f40c5f079edd004
---
 runtime/lua/vim/_meta/vimfn.lua | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index fa13c36a11..ff95edddf6 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3534,32 +3534,31 @@ function vim.fn.getreginfo(regname) end
 --- The optional argument {opts} is a Dict and supports the
 --- following items:
 ---
----   type    Specify the selection type
+---   type    Specify the region's selection type
 ---       (default: "v"):
 ---       "v"    for |charwise| mode
 ---       "V"    for |linewise| mode
 ---       ""  for |blockwise-visual| mode
 ---
 ---   exclusive  If |TRUE|, use exclusive selection
----       for the end position 'selection'.
+---       for the end position
+---       (default: follow 'selection')
 ---
 --- You can get the last selection type by |visualmode()|.
 --- If Visual mode is active, use |mode()| to get the Visual mode
 --- (e.g., in a |:vmap|).
---- This function uses the line and column number from the
---- specified position.
---- It is useful to get text starting and ending in different
---- columns, such as |charwise-visual| selection.
+--- This function is useful to get text starting and ending in
+--- different columns, such as a |charwise-visual| selection.
 ---
 --- Note that:
 --- - Order of {pos1} and {pos2} doesn't matter, it will always
 ---   return content from the upper left position to the lower
 ---   right position.
---- - If 'virtualedit' is enabled and selection is past the end of
----   line, resulting lines are filled with blanks.
---- - If the selection starts or ends in the middle of a multibyte
----   character, it is not included but its selected part is
----   substituted with spaces.
+--- - If 'virtualedit' is enabled and the region is past the end
+---   of the lines, resulting lines are padded with spaces.
+--- - If the region is blockwise and it starts or ends in the
+---   middle of a multi-cell character, it is not included but
+---   its selected part is substituted with spaces.
 --- - If {pos1} or {pos2} is not current in the buffer, an empty
 ---   list is returned.
 ---
-- 
cgit 


From 813dd36b72979dfd05479eb6402b9becc0faea29 Mon Sep 17 00:00:00 2001
From: Will Hopkins 
Date: Fri, 1 Mar 2024 14:59:32 -0800
Subject: fix(types): rename win_get_config return type to win_config

Follow-up to #27397
---
 runtime/lua/vim/_meta/api.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index d2f624fd97..94eab72291 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -2118,7 +2118,7 @@ function vim.api.nvim_win_get_buf(window) end
 --- `relative` is empty for normal windows.
 ---
 --- @param window integer Window handle, or 0 for current window
---- @return vim.api.keyset.float_config
+--- @return vim.api.keyset.win_config
 function vim.api.nvim_win_get_config(window) end
 
 --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window
-- 
cgit 


From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001
From: Lewis Russell 
Date: Tue, 27 Feb 2024 15:20:32 +0000
Subject: docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.
---
 runtime/lua/vim/_meta/builtin.lua | 1 +
 runtime/lua/vim/_meta/lpeg.lua    | 2 ++
 runtime/lua/vim/_meta/regex.lua   | 1 +
 3 files changed, 4 insertions(+)

(limited to 'runtime/lua/vim/_meta')

diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 472162ecc1..4831989e1a 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -61,6 +61,7 @@ error('Cannot require a meta file')
 ---
 ---
+---@nodoc ---@class vim.NIL ---@type vim.NIL diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 202c99f18c..1ce40f3340 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -21,6 +21,7 @@ error('Cannot require a meta file') vim.lpeg = {} +--- @nodoc --- @class vim.lpeg.Pattern --- @operator unm: vim.lpeg.Pattern --- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern @@ -167,6 +168,7 @@ function vim.lpeg.S(string) end --- @return vim.lpeg.Pattern function vim.lpeg.V(v) end +--- @nodoc --- @class vim.lpeg.Locale --- @field alnum userdata --- @field alpha userdata diff --git a/runtime/lua/vim/_meta/regex.lua b/runtime/lua/vim/_meta/regex.lua index ab403b97e7..595ad96319 100644 --- a/runtime/lua/vim/_meta/regex.lua +++ b/runtime/lua/vim/_meta/regex.lua @@ -12,6 +12,7 @@ --- @return vim.regex function vim.regex(re) end +--- @nodoc --- @class vim.regex local regex = {} -- luacheck: no unused -- cgit From ea44f74d84f87ce5aff2ef7797be986900bd74a6 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Wed, 6 Mar 2024 10:03:55 +0000 Subject: refactor(types): more fixes --- runtime/lua/vim/_meta/api_keysets_extra.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua index 8e34ee534c..d61dd2c02f 100644 --- a/runtime/lua/vim/_meta/api_keysets_extra.lua +++ b/runtime/lua/vim/_meta/api_keysets_extra.lua @@ -129,7 +129,7 @@ error('Cannot require a meta file') --- @field last_set_chan integer --- @field type 'string'|'boolean'|'number' --- @field default string|boolean|integer ---- @field allow_duplicates boolean +--- @field allows_duplicates boolean --- @class vim.api.keyset.parse_cmd.mods --- @field filter { force: boolean, pattern: string } -- cgit From 6525832a8c4d44a8ebabba02a5ea1ce09b389a4f Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Thu, 7 Mar 2024 06:43:08 +0800 Subject: vim-patch:9.1.0155: can only get getregion() from current buffer (#27757) Problem: can only call getregion() for current buffer Solution: Allow to retrieve selections from different buffers (Shougo Matsushita) closes: vim/vim#14131 https://github.com/vim/vim/commit/84bf6e658da51126bdd2e50af1f40cabd149343f Co-authored-by: Shougo Matsushita --- runtime/lua/vim/_meta/vimfn.lua | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index ff95edddf6..3c72d8be1d 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -3525,11 +3525,13 @@ function vim.fn.getreg(regname, list) end --- @return table function vim.fn.getreginfo(regname) end ---- Returns the list of strings from {pos1} to {pos2} in current +--- Returns the list of strings from {pos1} to {pos2} from a --- buffer. --- --- {pos1} and {pos2} must both be |List|s with four numbers. ---- See |getpos()| for the format of the list. +--- See |getpos()| for the format of the list. It's possible +--- to specify positions from a different buffer, but please +--- note the limitations at |getregion-notes| --- --- The optional argument {opts} is a Dict and supports the --- following items: @@ -3550,6 +3552,7 @@ function vim.fn.getreginfo(regname) end --- This function is useful to get text starting and ending in --- different columns, such as a |charwise-visual| selection. --- +--- *getregion-notes* --- Note that: --- - Order of {pos1} and {pos2} doesn't matter, it will always --- return content from the upper left position to the lower @@ -3559,8 +3562,12 @@ function vim.fn.getreginfo(regname) end --- - If the region is blockwise and it starts or ends in the --- middle of a multi-cell character, it is not included but --- its selected part is substituted with spaces. ---- - If {pos1} or {pos2} is not current in the buffer, an empty +--- - If {pos1} and {pos2} are not in the same buffer, an empty --- list is returned. +--- - {pos1} and {pos2} must belong to a |bufloaded()| buffer. +--- - It is evaluated in current window context, this makes a +--- different if a buffer is displayed in a different window and +--- 'virtualedit' or 'list' is set --- --- Examples: > --- :xnoremap -- cgit From 04232a19ccf0e49a3a19d0ef48221249d982b0d4 Mon Sep 17 00:00:00 2001 From: altermo <107814000+altermo@users.noreply.github.com> Date: Thu, 7 Mar 2024 09:16:05 +0100 Subject: fix(type): remove incorrect arguments from vim.rpc* --- runtime/lua/vim/_meta/builtin.lua | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index 4831989e1a..9a67667f02 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -91,9 +91,8 @@ function vim.empty_dict() end --- This function also works in a fast callback |lua-loop-callbacks|. --- @param channel integer --- @param method string ---- @param args? any[] --- @param ...? any -function vim.rpcnotify(channel, method, args, ...) end +function vim.rpcnotify(channel, method, ...) end --- Sends a request to {channel} to invoke {method} via |RPC| and blocks until --- a response is received. @@ -102,9 +101,8 @@ function vim.rpcnotify(channel, method, args, ...) end --- special value --- @param channel integer --- @param method string ---- @param args? any[] --- @param ...? any -function vim.rpcrequest(channel, method, args, ...) end +function vim.rpcrequest(channel, method, ...) end --- Compares strings case-insensitively. --- @param a string -- cgit From 5f3579e6ea12659d48e92b2126f83777908c28fc Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 8 Mar 2024 06:44:57 +0800 Subject: vim-patch:9.1.0157: Duplicate assignment in f_getregion() (#27766) Problem: Duplicate assignment in f_getregion(). Solution: Remove the duplicate assignment. Also improve getregion() docs wording and fix an unrelated typo (zeertzjq) closes: vim/vim#14154 https://github.com/vim/vim/commit/0df8f93bdaea77a1afb9f4eca94fe67ec73e6df2 --- runtime/lua/vim/_meta/vimfn.lua | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 3c72d8be1d..ac25547212 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -3531,7 +3531,7 @@ function vim.fn.getreginfo(regname) end --- {pos1} and {pos2} must both be |List|s with four numbers. --- See |getpos()| for the format of the list. It's possible --- to specify positions from a different buffer, but please ---- note the limitations at |getregion-notes| +--- note the limitations at |getregion-notes|. --- --- The optional argument {opts} is a Dict and supports the --- following items: @@ -3565,9 +3565,9 @@ function vim.fn.getreginfo(regname) end --- - If {pos1} and {pos2} are not in the same buffer, an empty --- list is returned. --- - {pos1} and {pos2} must belong to a |bufloaded()| buffer. ---- - It is evaluated in current window context, this makes a ---- different if a buffer is displayed in a different window and ---- 'virtualedit' or 'list' is set +--- - It is evaluated in current window context, which makes a +--- difference if the buffer is displayed in a window with +--- different 'virtualedit' or 'list' values. --- --- Examples: > --- :xnoremap -- cgit From d741e5d1629948876cf8bdcacf6c8bc8a4924f94 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 8 Mar 2024 06:52:14 +0800 Subject: vim-patch:9.1.0154: shm=F not respected when reloading buffer with 'autoread' Problem: shm=F not respected when reloading buffer with 'autoread' Solution: Check SHM_FILEINFO in buf_check_timestamp() (Shougo Matsushita) closes: vim/vim#14144 https://github.com/vim/vim/commit/9db39b0ec90600bb41faec3a12b934b17c298b1f Co-authored-by: Shougo Matsushita --- runtime/lua/vim/_meta/options.lua | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 5a9215fa9e..757720d8fb 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -5799,7 +5799,8 @@ vim.bo.sw = vim.bo.shiftwidth --- items, for instance "scanning tags" --- q do not show "recording @a" when recording a macro *shm-q* --- F don't give the file info when editing a file, like *shm-F* ---- `:silent` was used for the command +--- `:silent` was used for the command; note that this also +--- affects messages from 'autoread' reloading --- S do not show search count message when searching, e.g. *shm-S* --- "[1/5]" --- -- cgit From ade1b12f49c3b3914c74847d791eb90ea90b56b7 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 8 Mar 2024 12:25:18 +0000 Subject: docs: support inline markdown - Tags are now created with `[tag]()` - References are now created with `[tag]` - Code spans are no longer wrapped --- runtime/lua/vim/_meta/api.lua | 90 +++++++++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 37 deletions(-) (limited to 'runtime/lua/vim/_meta') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 94eab72291..cb4c8749b8 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -530,7 +530,7 @@ function vim.api.nvim_buf_line_count(buffer) end --- EOL of a line, continue the highlight for the rest of the --- screen line (just like for diff and cursorline highlight). --- • virt_text : virtual text to link to this mark. A list of ---- [text, highlight] tuples, each representing a text chunk +--- `[text, highlight]` tuples, each representing a text chunk --- with specified highlight. `highlight` element can either be --- a single highlight group, or an array of multiple highlight --- groups that will be stacked (highest priority last). A @@ -563,8 +563,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- for "inline" virt_text. --- • virt_lines : virtual lines to add next to this mark This --- should be an array over lines, where each line in turn is an ---- array over [text, highlight] tuples. In general, buffer and ---- window options do not affect the display of the text. In +--- array over `[text, highlight]` tuples. In general, buffer +--- and window options do not affect the display of the text. In --- particular 'wrap' and 'linebreak' options do not take --- effect, so the number of extra screen lines will always --- match the size of the array. However the 'tabstop' buffer @@ -690,9 +690,9 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. --- ---- To insert text at a given `(row, column)` location, use `start_row = ---- end_row = row` and `start_col = end_col = col`. To delete the text in a ---- range, use `replacement = {}`. +--- To insert text at a given `(row, column)` location, use +--- `start_row = end_row = row` and `start_col = end_col = col`. To delete the +--- text in a range, use `replacement = {}`. --- --- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire --- lines. @@ -903,9 +903,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- • event: (string) name of the triggered event --- `autocmd-events` --- • group: (number|nil) autocommand group id, if any ---- • match: (string) expanded value of `` ---- • buf: (number) expanded value of `` ---- • file: (string) expanded value of `` +--- • match: (string) expanded value of +--- • buf: (number) expanded value of +--- • file: (string) expanded value of --- • data: (any) arbitrary data passed from --- `nvim_exec_autocmds()` --- • command (string) optional: Vim command to execute on event. @@ -960,22 +960,21 @@ function vim.api.nvim_create_namespace(name) end --- argument that contains the following keys: --- • name: (string) Command name --- • args: (string) The args passed to the command, if any ---- `` +--- --- • fargs: (table) The args split by unescaped whitespace ---- (when more than one argument is allowed), if any ---- `` +--- (when more than one argument is allowed), if any --- • nargs: (string) Number of arguments `:command-nargs` --- • bang: (boolean) "true" if the command was executed with a ---- ! modifier `` +--- ! modifier --- • line1: (number) The starting line of the command range ---- `` +--- --- • line2: (number) The final line of the command range ---- `` +--- --- • range: (number) The number of items in the command range: ---- 0, 1, or 2 `` ---- • count: (number) Any count supplied `` ---- • reg: (string) The optional register, if specified `` ---- • mods: (string) Command modifiers, if any `` +--- 0, 1, or 2 +--- • count: (number) Any count supplied +--- • reg: (string) The optional register, if specified +--- • mods: (string) Command modifiers, if any --- • smods: (table) Command modifiers in a structured format. --- Has the same structure as the "mods" key of --- `nvim_parse_cmd()`. @@ -1049,9 +1048,9 @@ function vim.api.nvim_del_var(name) end --- Echo a message. --- ---- @param chunks any[] A list of [text, hl_group] arrays, each representing a text ---- chunk with specified highlight. `hl_group` element can be ---- omitted for no highlight. +--- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a +--- text chunk with specified highlight. `hl_group` element can +--- be omitted for no highlight. --- @param history boolean if true, add to `message-history`. --- @param opts vim.api.keyset.echo_opts Optional parameters. --- • verbose: Message was printed as a result of 'verbose' option @@ -1134,7 +1133,7 @@ function vim.api.nvim_exec2(src, opts) end --- • buffer (integer) optional: buffer number `autocmd-buflocal`. --- Cannot be used with {pattern}. --- • modeline (bool) optional: defaults to true. Process the ---- modeline after the autocommands ``. +--- modeline after the autocommands . --- • data (any): arbitrary data to send to the autocommand --- callback. See `nvim_create_autocmd()` for details. function vim.api.nvim_exec_autocmds(event, opts) end @@ -1541,7 +1540,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- be to the pty master end. For instance, a carriage return is --- sent as a "\r", not as a "\n". `textlock` applies. It is --- possible to call `nvim_chan_send()` directly in the callback ---- however. ["input", term, bufnr, data] +--- however. `["input", term, bufnr, data]` --- • force_crlf: (boolean, default true) Convert "\n" to "\r\n". --- @return integer function vim.api.nvim_open_term(buffer, opts) end @@ -1625,9 +1624,9 @@ function vim.api.nvim_open_term(buffer, opts) end --- • width: Window width (in character cells). Minimum of 1. --- • height: Window height (in character cells). Minimum of 1. --- • bufpos: Places float relative to buffer text (only when ---- relative="win"). Takes a tuple of zero-indexed [line, ---- column]. `row` and `col` if given are applied relative to ---- this position, else they default to: +--- relative="win"). Takes a tuple of zero-indexed +--- `[line, column]`. `row` and `col` if given are applied +--- relative to this position, else they default to: --- • `row=1` and `col=0` if `anchor` is "NW" or "NE" --- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus --- like a tooltip near the buffer text). @@ -1756,8 +1755,8 @@ function vim.api.nvim_parse_cmd(str, opts) end --- operator/space, though also yielding an error). --- • "l" when needing to start parsing with lvalues for ":let" --- or ":for". Common flag sets: ---- • "m" to parse like for ":echo". ---- • "E" to parse like for "=". +--- • "m" to parse like for `":echo"`. +--- • "E" to parse like for `"="`. --- • empty string for ":call". --- • "lm" to parse for ":let". --- @param highlight boolean If true, return value will also include "highlight" key @@ -1887,15 +1886,32 @@ function vim.api.nvim_set_current_win(window) end --- --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param opts vim.api.keyset.set_decoration_provider Table of callbacks: ---- • on_start: called first on each screen redraw ["start", tick] +--- • on_start: called first on each screen redraw +--- ``` +--- ["start", tick] +--- ``` +--- --- • on_buf: called for each buffer being redrawn (before window ---- callbacks) ["buf", bufnr, tick] +--- callbacks) +--- ``` +--- ["buf", bufnr, tick] +--- ``` +--- --- • on_win: called when starting to redraw a specific window. ---- ["win", winid, bufnr, topline, botline] +--- ``` +--- ["win", winid, bufnr, topline, botline] +--- ``` +--- --- • on_line: called for each buffer line being redrawn. (The ---- interaction with fold lines is subject to change) ["line", ---- winid, bufnr, row] ---- • on_end: called at the end of a redraw cycle ["end", tick] +--- interaction with fold lines is subject to change) +--- ``` +--- ["line", winid, bufnr, row] +--- ``` +--- +--- • on_end: called at the end of a redraw cycle +--- ``` +--- ["end", tick] +--- ``` function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- Sets a highlight group. @@ -1955,7 +1971,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- To set a buffer-local mapping, use `nvim_buf_set_keymap()`. --- --- Unlike `:map`, leading/trailing whitespace is accepted as part of the ---- {lhs} or {rhs}. Empty {rhs} is ``. `keycodes` are replaced as usual. +--- {lhs} or {rhs}. Empty {rhs} is . `keycodes` are replaced as usual. --- --- Example: --- @@ -1977,7 +1993,7 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- @param lhs string Left-hand-side `{lhs}` of the mapping. --- @param rhs string Right-hand-side `{rhs}` of the mapping. --- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys ---- except ``, values are booleans (default false). Also: +--- except , values are booleans (default false). Also: --- • "noremap" disables `recursive_mapping`, like `:noremap` --- • "desc" human-readable description. --- • "callback" Lua function called in place of {rhs}. -- cgit