diff --git a/.scripts/gen-function/gen-function.ts b/.scripts/gen-function/gen-function.ts index c139b6a5..ec331b87 100644 --- a/.scripts/gen-function/gen-function.ts +++ b/.scripts/gen-function/gen-function.ts @@ -5,8 +5,8 @@ import { DOCS_OVERRIDES } from "./override.ts"; import { transform } from "./transform.ts"; import { downloadString } from "../utils.ts"; -const VIM_VERSION = "9.1.0399"; -const NVIM_VERSION = "0.9.5"; +const VIM_VERSION = "9.1.0448"; +const NVIM_VERSION = "0.10.0"; const commonGenerateModule = "../../function/_generated.ts"; const vimGenerateModule = "../../function/vim/_generated.ts"; diff --git a/.scripts/gen-function/parse.ts b/.scripts/gen-function/parse.ts index 6d3a4744..6a59e02e 100644 --- a/.scripts/gen-function/parse.ts +++ b/.scripts/gen-function/parse.ts @@ -58,8 +58,11 @@ export function parse(content: string): Definition[] { } else { const line = content.substring(0, start + 1).split("\n").length; console.error( - `Failed to parse function definition for ${fn} at line ${line}`, + `Failed to parse function definition for '${fn}' at line ${line}:`, ); + console.error("----- block start -----"); + console.error(block); + console.error("----- block end -----"); } } return definitions; diff --git a/.scripts/gen-option/gen-option.ts b/.scripts/gen-option/gen-option.ts index 84825dd3..b3af9973 100644 --- a/.scripts/gen-option/gen-option.ts +++ b/.scripts/gen-option/gen-option.ts @@ -5,8 +5,8 @@ import { DOCS_OVERRIDES } from "./override.ts"; import { transform } from "./transform.ts"; import { downloadString } from "../utils.ts"; -const VIM_VERSION = "9.1.0399"; -const NVIM_VERSION = "0.9.5"; +const VIM_VERSION = "9.1.0448"; +const NVIM_VERSION = "0.10.0"; const commonGenerateModule = "../../option/_generated.ts"; const vimGenerateModule = "../../option/vim/_generated.ts"; @@ -36,7 +36,7 @@ for (const vimHelpDownloadUrl of vimHelpDownloadUrls) { console.log(`Download from ${vimHelpDownloadUrl}`); } const vimHelps = await Promise.all(vimHelpDownloadUrls.map(downloadString)); -const vimDefs = vimHelps.map(parse).flat(); +const vimDefs = parse(vimHelps.join("\n")); const vimOptionSet = new Set(vimDefs.map((def) => def.name)).difference( manualOptionSet, ); @@ -48,7 +48,7 @@ for (const nvimHelpDownloadUrl of nvimHelpDownloadUrls) { console.log(`Download from ${nvimHelpDownloadUrl}`); } const nvimHelps = await Promise.all(nvimHelpDownloadUrls.map(downloadString)); -const nvimDefs = nvimHelps.map(parse).flat(); +const nvimDefs = parse(nvimHelps.join("\n")); const nvimOptionSet = new Set(nvimDefs.map((def) => def.name)).difference( manualOptionSet, ); diff --git a/.scripts/gen-option/parse.ts b/.scripts/gen-option/parse.ts index c2286963..907f85ef 100644 --- a/.scripts/gen-option/parse.ts +++ b/.scripts/gen-option/parse.ts @@ -29,7 +29,7 @@ export function parse(content: string) { const options: Option[] = []; const succeeds = new Set(); - const errors: Array<{ name: string; start: number }> = []; + const errors: Array<{ name: string; start: number; block: string }> = []; let last = -1; for (const match of content.matchAll(/\*'(\w+)'\*/g)) { const name = match[1]; @@ -45,17 +45,20 @@ export function parse(content: string) { succeeds.add(start); last = end; } else { - errors.push({ name, start }); + errors.push({ name, start, block }); } } if (errors.length) { - for (const { name, start } of errors) { + for (const { name, start, block } of errors) { if (!succeeds.has(start)) { const line = content.substring(0, start + 1).split("\n").length; console.error( - `Failed to parse option definition for ${name} at line ${line}`, + `Failed to parse option definition for '${name}' at line ${line}:`, ); + console.error("----- block start -----"); + console.error(block); + console.error("----- block end -----"); } } } @@ -107,7 +110,8 @@ function parseBlock(name: string, body: string): Option | undefined { const reTags = /(?:[ \t]+\*[^*\s]+\*)+[ \t]*$/.source; const reShortNames = /(?:[ \t]+'\w+')*/.source; const reType = /[ \t]+(?\w+)/.source; - const reDefaults = /[ \t]+(?\(.*?(?:\n\t{3,}[ \t].*?)*?\))/.source; + const reDefaults = + /[ \t]+(?\(.*?(?:\n(?:\t{3,}| {24,})[ \t].*?)*?\))/.source; const reDefinition = `^'${name}'${reShortNames}(?:${reType}(?:${reDefaults})?)?(?:${reTags})?$`; const m1 = body.match(new RegExp(reDefinition, "dm")); diff --git a/.scripts/markdown.ts b/.scripts/markdown.ts index 3c4234c8..bad14142 100644 --- a/.scripts/markdown.ts +++ b/.scripts/markdown.ts @@ -12,8 +12,8 @@ export function createMarkdownFromHelp(body: string): string { const codeBlockIndent = " "; let lastIndent = firstlineIndent; body = body.replaceAll( - /(?.*?)[\n ]>\n(?.*?)(?:\n(?=<)|$)|(?.*)/gs, - (_, normal: string, code: string, rest: string) => { + /(?.*?)[\n ]>(?\w*)\n(?.*?)(?:\n(?=<)|$)|(?.*)/gs, + (_, normal: string, _ft: string, code: string, rest: string) => { if (rest !== undefined) { return formatNormalBlock(rest); } diff --git a/.scripts/utils.ts b/.scripts/utils.ts index 0687eb36..68db5d37 100644 --- a/.scripts/utils.ts +++ b/.scripts/utils.ts @@ -6,7 +6,7 @@ import * as streams from "@std/streams"; */ export async function downloadString(url: string): Promise { const response = await fetch(url); - if (!response.body) { + if (response.status >= 400 || !response.body) { throw new Error(`Failed to read ${url}`); } //const reader = streams.readerFromStreamReader(response.body.getReader()); diff --git a/function/_generated.ts b/function/_generated.ts index 2e22eade..484fbc75 100644 --- a/function/_generated.ts +++ b/function/_generated.ts @@ -2357,6 +2357,57 @@ export function foldtextresult( return denops.call("foldtextresult", ...args); } +/** + * **{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, 'used[v:val] = true') + * + * This records the items that are in the **{expr1}** list. + * + * Note that **{expr2}** is the result of expression and is then used + * as a command. Often it is good to use a `literal-string` to + * avoid having to double backslashes. + * + * If **{expr2}** is a `Funcref` it must take two arguments: + * 1. the key or the index of the current item. + * 2. the value of the current item. + * With a legacy script lambda you don't get an error if it only + * accepts one argument, but with a Vim9 lambda you get "E1106: + * One argument too many", the number of arguments must match. + * If the function returns a value, it is ignored. + * + * Returns **{expr1}** in all cases. + * When an error is encountered while executing **{expr2}** no + * further items in **{expr1}** are processed. + * When **{expr2}** is a Funcref errors inside a function are ignored, + * unless it was defined with the "abort" flag. + * + * Can also be used as a `method`: + * + * mylist->foreach(expr2) + */ +export function foreach( + denops: Denops, + expr1: unknown, + expr2: unknown, +): Promise | unknown | string>; +export function foreach(denops: Denops, ...args: unknown[]): Promise { + return denops.call("foreach", ...args); +} + /** * Get the full command name from a short abbreviated command * name; see `20.2` for details on command abbreviations. @@ -3528,6 +3579,73 @@ export function getreg(denops: Denops, ...args: unknown[]): Promise { return denops.call("getreg", ...args); } +/** + * 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. 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: + * + * type Specify the region's selection type. + * See `getregtype()` for possible values, + * except that the width can be omitted + * and an empty string cannot be used. + * (default: "v") + * + * exclusive If `TRUE`, use exclusive 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 is useful to get text starting and ending in + * different columns, such as a `characterwise-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 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}** 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, which makes a + * difference if the buffer is displayed in a window with + * different 'virtualedit' or 'list' values. + * + * Examples: + * + * :xnoremap + * \ echow getregion( + * \ getpos('v'), getpos('.'), #{ type: mode() }) + * + * Can also be used as a `method`: + * + * getpos('.')->getregion(getpos("'a")) + */ +export function getregion( + denops: Denops, + pos1: unknown, + pos2: unknown, + opts?: unknown, +): Promise; +export function getregion( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("getregion", ...args); +} + /** * The result is a String, which is type of register **{regname}**. * The value will be one of: @@ -5057,6 +5175,35 @@ export function log10(denops: Denops, ...args: unknown[]): Promise { return denops.call("log10", ...args); } +/** + * Evaluate Lua expression **{expr}** and return its result converted + * to Vim data structures. Second **{expr}** may hold additional + * argument accessible as _A inside first **{expr}**. + * Strings are returned as they are. + * Boolean objects are converted to numbers. + * Numbers are converted to `Float` values. + * Dictionaries and lists obtained by vim.eval() are returned + * as-is. + * Other objects are returned as zero without any errors. + * See `lua-luaeval` for more details. + * Note that in a `:def` function local variables are not visible + * to **{expr}**. + * + * Can also be used as a `method`: + * + * GetExpr()->luaeval() + * + * *only available when compiled with the `+lua` feature* + */ +export function luaeval( + denops: Denops, + expr1: unknown, + expr2?: unknown, +): Promise; +export function luaeval(denops: Denops, ...args: unknown[]): Promise { + return denops.call("luaeval", ...args); +} + /** * **{expr1}** must be a `List`, `String`, `Blob` or `Dictionary`. * When **{expr1}** is a `List` or `Dictionary`, replace each @@ -5276,6 +5423,64 @@ export function mapcheck(denops: Denops, ...args: unknown[]): Promise { return denops.call("mapcheck", ...args); } +/** + * Returns a `List` of all mappings. Each List item is a `Dict`, + * the same as what is returned by `maparg()`, see + * `mapping-dict`. When **{abbr}** is there and it is `TRUE` use + * abbreviations instead of mappings. + * + * Example to show all mappings with 'MultiMatch' in rhs: + * + * vim9script + * echo maplist()->filter( + * (_, m) => match(m.rhs, 'MultiMatch') >= 0) + * + * It can be tricky to find mappings for particular `:map-modes`. + * `mapping-dict`'s "mode_bits" can simplify this. For example, + * the mode_bits for Normal, Insert or Command-line modes are + * 0x19. To find all the mappings available in those modes you + * can do: + * + * vim9script + * var saved_maps = [] + * for m in maplist() + * if and(m.mode_bits, 0x19) != 0 + * saved_maps->add(m) + * endif + * endfor + * echo saved_maps->mapnew((_, m) => m.lhs) + * + * The values of the mode_bits are defined in Vim's src/vim.h + * file and they can be discovered at runtime using + * `:map-commands` and "maplist()". Example: + * + * vim9script + * omap xyzzy + * var op_bit = maplist()->filter( + * (_, m) => m.lhs == 'xyzzy')[0].mode_bits + * ounmap xyzzy + * echo printf("Operator-pending mode bit: 0x%x", op_bit) + */ +export function maplist(denops: Denops, abbr?: unknown): Promise; +export function maplist(denops: Denops, ...args: unknown[]): Promise { + return denops.call("maplist", ...args); +} + +/** + * Like `map()` but instead of replacing items in **{expr1}** a new + * List or Dictionary is created and returned. **{expr1}** remains + * unchanged. Items can still be changed by **{expr2}**, if you + * don't want that use `deepcopy()` first. + */ +export function mapnew( + denops: Denops, + expr1: unknown, + expr2: unknown, +): Promise | unknown | string>; +export function mapnew(denops: Denops, ...args: unknown[]): Promise { + return denops.call("mapnew", ...args); +} + /** * Restore a mapping from a dictionary, possibly returned by * `maparg()` or `maplist()`. A buffer mapping, when dict.buffer @@ -5570,6 +5775,72 @@ export function matcharg(denops: Denops, ...args: unknown[]): Promise { return denops.call("matcharg", ...args); } +/** + * 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. + * + * 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. + * + * Examples: + * + * " 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: + * + * " 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', '', '', '', '', '']}] + * + * The "submatches" List always contains 9 items. If a submatch + * is not found, then an empty string is returned for that + * submatch. + * + * Can also be used as a `method`: + * + * GetBuffer()->matchbufline('mypat', 1, '$') + */ +export function matchbufline( + denops: Denops, + buf: unknown, + pat: unknown, + lnum: unknown, + end: unknown, + dict?: unknown, +): Promise; +export function matchbufline( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("matchbufline", ...args); +} + /** * Deletes a match with ID **{id}** previously defined by `matchadd()` * or one of the `:match` commands. Returns 0 if successful, @@ -5800,6 +6071,59 @@ export function matchlist( return denops.call("matchlist", ...args); } +/** + * Returns the `List` of matches in **{list}** where **{pat}** matches. + * **{list}** is a `List` of strings. **{pat}** is matched against each + * string in **{list}**. + * + * 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. + * idx index in **{list}** of the match. + * text matched string + * 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: + * + * :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: + * + * :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', + * \ #{submatches: v:true}) + * [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] + * + * The "submatches" List always contains 9 items. If a submatch + * is not found, then an empty string is returned for that + * submatch. + * + * Can also be used as a `method`: + * + * GetListOfStrings()->matchstrlist('mypat') + */ +export function matchstrlist( + denops: Denops, + list: unknown, + pat: unknown, + dict?: unknown, +): Promise; +export function matchstrlist( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("matchstrlist", ...args); +} + /** * Same as `match()`, but return the matched string. Example: * @@ -8717,11 +9041,12 @@ export function sha256(denops: Denops, ...args: unknown[]): Promise { * Otherwise it will enclose **{string}** in single quotes and * replace all "'" with "'\''". * - * When the **{special}** argument is present and it's a non-zero - * Number or a non-empty String (`non-zero-arg`), then special - * items such as "!", "%", "#" and `""` will be preceded by - * a backslash. This backslash will be removed again by the `:!` - * command. + * The **{special}** argument adds additional escaping of keywords + * used in Vim commands. When it is not omitted and a non-zero + * number or a non-empty String (`non-zero-arg`), then special + * items such as "!", "%", "#" and `""` (as listed in + * `expand()`) will be preceded by a backslash. + * This backslash will be removed again by the `:!` command. * * The "!" character will be escaped (again with a `non-zero-arg` * **{special}**) when 'shell' contains "csh" in the tail. That is @@ -8862,6 +9187,30 @@ export function sinh(denops: Denops, ...args: unknown[]): Promise { return denops.call("sinh", ...args); } +/** + * Similar to using a `slice` "expr[start : end]", but "end" is + * used exclusive. And for a string the indexes are used as + * character indexes instead of byte indexes, like in + * `vim9script`. Also, composing characters are treated as a + * part of the preceding base character. + * When **{end}** is omitted the slice continues to the last item. + * When **{end}** is -1 the last item is omitted. + * Returns an empty value if **{start}** or **{end}** are invalid. + * + * Can also be used as a `method`: + * + * GetList()->slice(offset) + */ +export function slice( + denops: Denops, + expr: unknown, + start: unknown, + end?: unknown, +): Promise; +export function slice(denops: Denops, ...args: unknown[]): Promise { + return denops.call("slice", ...args); +} + /** * Sort the items in **{list}** in-place. Returns **{list}**. * @@ -9149,6 +9498,48 @@ export function srand(denops: Denops, ...args: unknown[]): Promise { return denops.call("srand", ...args); } +/** + * Return a string which contains characters indicating the + * current state. Mostly useful in callbacks that want to do + * work that may not always be safe. Roughly this works like: + * - callback uses state() to check if work is safe to do. + * Yes: then do it right away. + * No: add to work queue and add a `SafeState` and/or + * `SafeStateAgain` autocommand (`SafeState` triggers at + * toplevel, `SafeStateAgain` triggers after handling + * messages and callbacks). + * - When SafeState or SafeStateAgain is triggered and executes + * your autocommand, check with `state()` if the work can be + * done now, and if yes remove it from the queue and execute. + * Remove the autocommand if the queue is now empty. + * Also see `mode()`. + * + * When **{what}** is given only characters in this string will be + * added. E.g, this checks if the screen has scrolled: + * + * if state('s') == '' + * " screen has not scrolled + * + * These characters indicate the state, generally indicating that + * something is busy: + * m halfway a mapping, :normal command, feedkeys() or + * stuffed command + * o operator pending, e.g. after `d` + * a Insert mode autocomplete active + * x executing an autocommand + * w blocked on waiting, e.g. ch_evalexpr(), ch_read() and + * ch_readraw() when reading json + * S not triggering SafeState or SafeStateAgain, e.g. after + * `f` or a count + * c callback invoked, including timer (repeats for + * recursiveness up to "ccc") + * s screen has scrolled for messages + */ +export function state(denops: Denops, what?: unknown): Promise; +export function state(denops: Denops, ...args: unknown[]): Promise { + return denops.call("state", ...args); +} + /** * Convert String **{string}** to a Float. This mostly works the * same as when using a floating point number in an expression, @@ -9672,6 +10063,42 @@ export function strtrans(denops: Denops, ...args: unknown[]): Promise { return denops.call("strtrans", ...args); } +/** + * The result is a Number, which is the number of UTF-16 code + * units in String **{string}** (after converting it to UTF-16). + * + * When **{countcc}** is TRUE, composing characters are counted + * separately. + * When **{countcc}** is omitted or FALSE, composing characters are + * ignored. + * + * Returns zero on error. + * + * Also see `strlen()` and `strcharlen()`. + * Examples: + * + * echo strutf16len('a') returns 1 + * echo strutf16len('©') returns 1 + * echo strutf16len('😊') returns 2 + * echo strutf16len('ą́') returns 1 + * echo strutf16len('ą́', v:true) returns 3 + * + * Can also be used as a `method`: + * + * GetText()->strutf16len() + */ +export function strutf16len( + denops: Denops, + string: unknown, + countcc?: unknown, +): Promise; +export function strutf16len( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("strutf16len", ...args); +} + /** * The result is a Number, which is the number of display cells * String **{string}** occupies. A Tab character is counted as one @@ -9802,6 +10229,26 @@ export function substitute( return denops.call("substitute", ...args); } +/** + * Returns a list of swap file names, like what "vim -r" shows. + * See the `-r` command argument. The 'directory' option is used + * for the directories to inspect. If you only want to get a + * list of swap files in the current directory then temporarily + * set 'directory' to a dot: + * + * let save_dir = &directory + * let &directory = '.' + * let swapfiles = swapfilelist() + * let &directory = save_dir + */ +export function swapfilelist(denops: Denops): Promise; +export function swapfilelist( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("swapfilelist", ...args); +} + /** * The result is a dictionary, which holds information about the * swapfile **{fname}**. The available fields are: @@ -10328,7 +10775,9 @@ export function tanh(denops: Denops, ...args: unknown[]): Promise { * :let tmpfile = tempname() * :exe "redir > " .. tmpfile * - * For Unix, the file will be in a private directory `tempfile`. + * For Unix, the file will be in a private directory `tempfile` + * that is recursively deleted when Vim exits, on other systems + * temporary files are not cleaned up automatically on exit. * For MS-Windows forward slashes are used when the 'shellslash' * option is set, or when 'shellcmdflag' starts with '-' and * 'shell' does not contain powershell or pwsh. @@ -10773,6 +11222,49 @@ export function uniq(denops: Denops, ...args: unknown[]): Promise { return denops.call("uniq", ...args); } +/** + * Same as `charidx()` but returns the UTF-16 code unit index of + * the byte at **{idx}** in **{string}** (after converting it to UTF-16). + * + * When **{charidx}** is present and TRUE, **{idx}** is used as the + * character index in the String **{string}** instead of as the byte + * index. + * An **{idx}** in the middle of a UTF-8 sequence is rounded + * downwards to the beginning of that sequence. + * + * Returns -1 if the arguments are invalid or if there are less + * than **{idx}** bytes in **{string}**. If there are exactly **{idx}** bytes + * the length of the string in UTF-16 code units is returned. + * + * See `byteidx()` and `byteidxcomp()` for getting the byte index + * from the UTF-16 index and `charidx()` for getting the + * character index from the UTF-16 index. + * Refer to `string-offset-encoding` for more information. + * Examples: + * + * echo utf16idx('a😊😊', 3) returns 2 + * echo utf16idx('a😊😊', 7) returns 4 + * echo utf16idx('a😊😊', 1, 0, 1) returns 2 + * echo utf16idx('a😊😊', 2, 0, 1) returns 4 + * echo utf16idx('aą́c', 6) returns 2 + * echo utf16idx('aą́c', 6, 1) returns 4 + * echo utf16idx('a😊😊', 9) returns -1 + * + * Can also be used as a `method`: + * + * GetName()->utf16idx(idx) + */ +export function utf16idx( + denops: Denops, + string: unknown, + idx: unknown, + countcc?: unknown, + charidx?: unknown, +): Promise; +export function utf16idx(denops: Denops, ...args: unknown[]): Promise { + return denops.call("utf16idx", ...args); +} + /** * Return a `List` with all the values of **{dict}**. The `List` is * in arbitrary order. Also see `items()` and `keys()`. @@ -12027,3 +12519,371 @@ export function sign_unplacelist( ): Promise { return denops.call("sign_unplacelist", ...args); } + +/** + * Like garbagecollect(), but executed right away. This must + * only be called directly to avoid any structure to exist + * internally, and `v:testing` must have been set before calling + * any function. + * This will not work when called from a :def function, because + * variables on the stack will be freed. + */ +export function test_garbagecollect_now(denops: Denops): Promise; +export function test_garbagecollect_now( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("test_garbagecollect_now", ...args); +} + +/** + * Run **{cmd}** and add an error message to `v:errors` if it does + * NOT produce a beep or visual bell. + * Also see `assert_fails()`, `assert_nobeep()` and + * `assert-return`. + * + * Can also be used as a `method`: + * + * GetCmd()->assert_beeps() + */ +export function assert_beeps(denops: Denops, cmd: unknown): Promise; +export function assert_beeps( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_beeps", ...args); +} + +/** + * When **{expected}** and **{actual}** are not equal an error message is + * added to `v:errors` and 1 is returned. Otherwise zero is + * returned. `assert-return` + * The error is in the form "Expected **{expected}** but got + * **{actual}**". When **{msg}** is present it is prefixed to that. + * + * There is no automatic conversion, the String "4" is different + * from the Number 4. And the number 4 is different from the + * Float 4.0. The value of 'ignorecase' is not used here, case + * always matters. + * Example: + * + * assert_equal('foo', 'bar') + * + * Will result in a string to be added to `v:errors`: + * test.vim line 12: Expected 'foo' but got 'bar' + * + * Can also be used as a `method`, the base is passed as the + * second argument: + * + * mylist->assert_equal([1, 2, 3]) + */ +export function assert_equal( + denops: Denops, + expected: unknown, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_equal( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_equal", ...args); +} + +/** + * When the files **{fname-one}** and **{fname-two}** do not contain + * exactly the same text an error message is added to `v:errors`. + * Also see `assert-return`. + * When **{fname-one}** or **{fname-two}** does not exist the error will + * mention that. + * Mainly useful with `terminal-diff`. + * + * Can also be used as a `method`: + * + * GetLog()->assert_equalfile('expected.log') + */ +export function assert_equalfile( + denops: Denops, + fname_one: unknown, + fname_two: unknown, + msg?: unknown, +): Promise; +export function assert_equalfile( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_equalfile", ...args); +} + +/** + * When v:exception does not contain the string **{error}** an error + * message is added to `v:errors`. Also see `assert-return`. + * This can be used to assert that a command throws an exception. + * Using the error number, followed by a colon, avoids problems + * with translations: + * + * try + * commandthatfails + * call assert_false(1, 'command should have failed') + * catch + * call assert_exception('E492:') + * endtry + */ +export function assert_exception( + denops: Denops, + error: unknown, + msg?: unknown, +): Promise; +export function assert_exception( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_exception", ...args); +} + +/** + * Run **{cmd}** and add an error message to `v:errors` if it does + * NOT produce an error or when **{error}** is not found in the + * error message. Also see `assert-return`. + * + * When **{error}** is a string it must be found literally in the + * first reported error. Most often this will be the error code, + * including the colon, e.g. "E123:". + * + * assert_fails('bad cmd', 'E987:') + * + * When **{error}** is a `List` with one or two strings, these are + * used as patterns. The first pattern is matched against the + * first reported error: + * + * assert_fails('cmd', ['E987:.*expected bool']) + * + * The second pattern, if present, is matched against the last + * reported error. + * If there is only one error then both patterns must match. This + * can be used to check that there is only one error. + * To only match the last error use an empty string for the first + * error: + * + * assert_fails('cmd', ['', 'E987:']) + * + * If **{msg}** is empty then it is not used. Do this to get the + * default message when passing the **{lnum}** argument. + * + * When **{lnum}** is present and not negative, and the **{error}** + * argument is present and matches, then this is compared with + * the line number at which the error was reported. That can be + * the line number in a function or in a script. + * + * When **{context}** is present it is used as a pattern and matched + * against the context (script name or function name) where + * **{lnum}** is located in. + * + * Note that beeping is not considered an error, and some failing + * commands only beep. Use `assert_beeps()` for those. + * + * Can also be used as a `method`: + * + * GetCmd()->assert_fails('E99:') + */ +export function assert_fails( + denops: Denops, + cmd: unknown, + error?: unknown, + msg?: unknown, + lnum?: unknown, + context?: unknown, +): Promise; +export function assert_fails( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_fails", ...args); +} + +/** + * When **{actual}** is not false an error message is added to + * `v:errors`, like with `assert_equal()`. + * The error is in the form "Expected False but got **{actual}**". + * When **{msg}** is present it is prepended to that. + * Also see `assert-return`. + * + * A value is false when it is zero. When **{actual}** is not a + * number the assert fails. + * + * Can also be used as a `method`: + * + * GetResult()->assert_false() + */ +export function assert_false( + denops: Denops, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_false( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_false", ...args); +} + +/** + * This asserts number and `Float` values. When **{actual}** is lower + * than **{lower}** or higher than **{upper}** an error message is added + * to `v:errors`. Also see `assert-return`. + * The error is in the form "Expected range **{lower}** - **{upper}**, + * but got **{actual}**". When **{msg}** is present it is prefixed to + * that. + */ +export function assert_inrange( + denops: Denops, + lower: unknown, + upper: unknown, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_inrange( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_inrange", ...args); +} + +/** + * When **{pattern}** does not match **{actual}** an error message is + * added to `v:errors`. Also see `assert-return`. + * The error is in the form "Pattern **{pattern}** does not match + * **{actual}**". When **{msg}** is present it is prefixed to that. + * + * **{pattern}** is used as with `=~`: The matching is always done + * like 'magic' was set and 'cpoptions' is empty, no matter what + * the actual value of 'magic' or 'cpoptions' is. + * + * **{actual}** is used as a string, automatic conversion applies. + * Use "^" and "$" to match with the start and end of the text. + * Use both to match the whole text. + * + * Example: + * + * assert_match('^f.*o$', 'foobar') + * + * Will result in a string to be added to `v:errors`: + * test.vim line 12: Pattern '^f.*o$' does not match 'foobar' + * + * Can also be used as a `method`: + * + * getFile()->assert_match('foo.*') + */ +export function assert_match( + denops: Denops, + pattern: unknown, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_match( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_match", ...args); +} + +/** + * Run **{cmd}** and add an error message to `v:errors` if it + * produces a beep or visual bell. + * Also see `assert_beeps()`. + * + * Can also be used as a `method`: + * + * GetCmd()->assert_nobeep() + */ +export function assert_nobeep(denops: Denops, cmd: unknown): Promise; +export function assert_nobeep( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_nobeep", ...args); +} + +/** + * The opposite of `assert_equal()`: add an error message to + * `v:errors` when **{expected}** and **{actual}** are equal. + * Also see `assert-return`. + * + * Can also be used as a `method`: + * + * mylist->assert_notequal([1, 2, 3]) + */ +export function assert_notequal( + denops: Denops, + expected: unknown, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_notequal( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_notequal", ...args); +} + +/** + * The opposite of `assert_match()`: add an error message to + * `v:errors` when **{pattern}** matches **{actual}**. + * Also see `assert-return`. + * + * Can also be used as a `method`: + * + * getFile()->assert_notmatch('bar.*') + */ +export function assert_notmatch( + denops: Denops, + pattern: unknown, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_notmatch( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_notmatch", ...args); +} + +/** + * Report a test failure directly, using String **{msg}**. + * Always returns one. + * + * Can also be used as a `method`: + * + * GetMessage()->assert_report() + */ +export function assert_report(denops: Denops, msg: unknown): Promise; +export function assert_report( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_report", ...args); +} + +/** + * When **{actual}** is not true an error message is added to + * `v:errors`, like with `assert_equal()`. + * Also see `assert-return`. + * A value is TRUE when it is a non-zero number. When **{actual}** + * is not a number the assert fails. + * When **{msg}** is given it precedes the default message. + * + * Can also be used as a `method`: + * + * GetResult()->assert_true() + */ +export function assert_true( + denops: Denops, + actual: unknown, + msg?: unknown, +): Promise; +export function assert_true( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("assert_true", ...args); +} diff --git a/function/common.ts b/function/common.ts index 27886fc3..0b26f897 100644 --- a/function/common.ts +++ b/function/common.ts @@ -130,16 +130,16 @@ export async function exists( * **{feature}** argument is a feature name like "nvim-0.2.1" or * "win32", see below. See also `exists()`. * - * To get the system name use `vim.loop`.os_uname() in Lua: + * To get the system name use `vim.uv`.os_uname() in Lua: * - * :lua print(vim.loop.os_uname().sysname) + * print(vim.uv.os_uname().sysname) * * If the code has a syntax error then Vimscript may skip the * rest of the line. Put `:if` and `:endif` on separate lines to * avoid the syntax error: * * if has('feature') - * let x = this->breaks->without->the->feature + * let x = this_breaks_without_the_feature() * endif * * Vim's compile-time feature-names (prefixed with "+") are not @@ -150,12 +150,16 @@ export async function exists( * 1. Nvim version. For example the "nvim-0.2.1" feature means * that Nvim is version 0.2.1 or later: * - * :if has("nvim-0.2.1") + * if has("nvim-0.2.1") + * " ... + * endif * * 2. Runtime condition or other pseudo-feature. For example the * "win32" feature checks if the current system is Windows: * - * :if has("win32") + * if has("win32") + * " ... + * endif * * List of supported pseudo-feature names: * acl `ACL` support. @@ -182,12 +186,16 @@ export async function exists( * 3. Vim patch. For example the "patch123" feature means that * Vim patch 123 at the current `v:version` was included: * - * :if v:version > 602 || v:version == 602 && has("patch148") + * if v:version > 602 || v:version == 602 && has("patch148") + * " ... + * endif * * 4. Vim version. For example the "patch-7.4.237" feature means * that Nvim is Vim-compatible to version 7.4.237 or later. * - * :if has("patch-7.4.237") + * if has("patch-7.4.237") + * " ... + * endif */ export async function has( denops: Denops, diff --git a/function/nvim/_generated.ts b/function/nvim/_generated.ts index f8eb4211..97b157e0 100644 --- a/function/nvim/_generated.ts +++ b/function/nvim/_generated.ts @@ -2,182 +2,6 @@ // deno-lint-ignore-file camelcase import type { Denops } from "@denops/core"; -/** - * Find files in runtime directories - * - * Attributes: - * `api-fast` - * - * Parameters: - * - **{pat}** pattern of files to search for - * - **{all}** whether to return all matches or only the first - * - **{opts}** is_lua: only search lua subdirs - * - * Return: - * list of absolute paths to the found files - */ -export function nvim__get_runtime( - denops: Denops, - pat: unknown, - all: unknown, - opts: unknown, -): Promise; -export function nvim__get_runtime( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim__get_runtime", ...args); -} - -/** - * Returns object given as argument. - * - * This API function is used for testing. One should not rely on its presence - * in plugins. - * - * Parameters: - * - **{obj}** Object to return. - * - * Return: - * its argument. - */ -export function nvim__id(denops: Denops, obj: unknown): Promise; -export function nvim__id(denops: Denops, ...args: unknown[]): Promise { - return denops.call("nvim__id", ...args); -} - -/** - * Returns array given as argument. - * - * This API function is used for testing. One should not rely on its presence - * in plugins. - * - * Parameters: - * - **{arr}** Array to return. - * - * Return: - * its argument. - */ -export function nvim__id_array(denops: Denops, arr: unknown): Promise; -export function nvim__id_array( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim__id_array", ...args); -} - -/** - * Returns dictionary given as argument. - * - * This API function is used for testing. One should not rely on its presence - * in plugins. - * - * Parameters: - * - **{dct}** Dictionary to return. - * - * Return: - * its argument. - */ -export function nvim__id_dictionary( - denops: Denops, - dct: unknown, -): Promise; -export function nvim__id_dictionary( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim__id_dictionary", ...args); -} - -/** - * Returns floating-point value given as argument. - * - * This API function is used for testing. One should not rely on its presence - * in plugins. - * - * Parameters: - * - **{flt}** Value to return. - * - * Return: - * its argument. - */ -export function nvim__id_float(denops: Denops, flt: unknown): Promise; -export function nvim__id_float( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim__id_float", ...args); -} - -/** - * NB: if your UI doesn't use hlstate, this will not return hlstate first - * time. - */ -export function nvim__inspect_cell( - denops: Denops, - grid: unknown, - row: unknown, - col: unknown, -): Promise; -export function nvim__inspect_cell( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim__inspect_cell", ...args); -} - -/** - * Gets internal stats. - * - * Return: - * Map of various internal stats. - */ -export function nvim__stats(denops: Denops): Promise; -export function nvim__stats( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim__stats", ...args); -} - -/** - * Calls many API methods atomically. - * - * This has two main usages: - * 1. To perform several requests from an async context atomically, i.e. - * without interleaving redraws, RPC requests from other clients, or user - * interactions (however API methods may trigger autocommands or event - * processing which have such side effects, e.g. `:sleep` may wake - * timers). - * 2. To minimize RPC overhead (roundtrips) of a sequence of many requests. - * - * Attributes: - * `RPC` only - * - * Parameters: - * - **{calls}** an array of calls, where each call is described by an array - * with two elements: the request name, and an array of - * arguments. - * - * Return: - * Array of two elements. The first is an array of return values. The - * second is NIL if all calls succeeded. If a call resulted in an error, - * it is a three-element array with the zero-based index of the call - * which resulted in an error, the error type and the error message. If - * an error occurred, the values from all preceding calls will still be - * returned. - */ -export function nvim_call_atomic( - denops: Denops, - calls: unknown, -): Promise; -export function nvim_call_atomic( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_call_atomic", ...args); -} - /** * Send data to channel `id`. For a job, it writes it to the stdin of the * process. For the stdio channel `channel-stdio`, it writes to Nvim's @@ -273,7 +97,7 @@ export function nvim_del_keymap( * Deletes an uppercase/file named mark. See `mark-motions`. * * Note: - * fails with error if a lowercase or buffer local named mark is used. + * - Lowercase name (or other buffer-local mark) is an error. * * Parameters: * - **{name}** Mark name @@ -311,9 +135,9 @@ export function nvim_del_var( * Echo a message. * * Parameters: - * - **{chunks}** A list of [text, hl_group] arrays, each representing a text - * chunk with specified highlight. `hl_group` element can be - * omitted for no highlight. + * - **{chunks}** A list of `[text, hl_group]` arrays, each representing a + * text chunk with specified highlight. `hl_group` element can + * be omitted for no highlight. * - **{history}** if true, add to `message-history`. * - **{opts}** Optional parameters. * - verbose: Message was printed as a result of 'verbose' @@ -455,10 +279,10 @@ export function nvim_exec_lua( * with escape_ks=false) to replace `keycodes`, then pass the result to * nvim_feedkeys(). * - * Example: >vim - * :let key = nvim_replace_termcodes(`""`, v:true, v:false, v:true) + * Example: + * + * :let key = nvim_replace_termcodes("", v:true, v:false, v:true) * :call nvim_feedkeys(key, 'n', v:false) - * < * * Parameters: * - **{keys}** to be typed @@ -488,12 +312,12 @@ export function nvim_feedkeys( * Returns a 2-tuple (Array), where item 0 is the current channel id and item * 1 is the `api-metadata` map (Dictionary). * - * Return: - * 2-tuple [**{channel-id}**, **{api-metadata}**] - * * Attributes: * `api-fast` * `RPC` only + * + * Return: + * 2-tuple `[{channel-id}, {api-metadata}]` */ export function nvim_get_api_info(denops: Denops): Promise; export function nvim_get_api_info( @@ -506,6 +330,9 @@ export function nvim_get_api_info( /** * Gets information about a channel. * + * Parameters: + * - **{chan}** channel_id, or 0 for current channel + * * Return: * Dictionary describing a channel, with these keys: * - "id" Channel id. @@ -515,12 +342,10 @@ export function nvim_get_api_info( * - "stderr" stderr of this Nvim instance * - "socket" TCP/IP socket or named pipe * - "job" Job with communication over its stdio. - * * - "mode" How data received on the channel is interpreted. * - "bytes" Send and receive raw bytes. * - "terminal" `terminal` instance interprets ASCII sequences. * - "rpc" `RPC` communication on the channel is active. - * * - "pty" (optional) Name of pseudoterminal. On a POSIX system this is a * device path like "/dev/pts/1". If the name is unknown, the key will * still be present if a pty is used (e.g. for conpty on Windows). @@ -543,10 +368,10 @@ export function nvim_get_chan_info( * Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or * "#rrggbb" hexadecimal string. * - * Example: >vim + * Example: + * * :echo nvim_get_color_by_name("Pink") * :echo nvim_get_color_by_name("#cbcbcb") - * < * * Parameters: * - **{name}** Color name or "#rrggbb" string @@ -663,6 +488,10 @@ export function nvim_get_current_win( /** * Gets all or specific highlight groups in a namespace. * + * Note: + * - When the `link` attribute is defined in the highlight definition map, + * other attributes will not be taking effect (see `:hi-link`). + * * Parameters: * - {ns_id} Get highlight groups for namespace ns_id * `nvim_get_namespaces()`. Use 0 to get global highlight groups @@ -672,15 +501,13 @@ export function nvim_get_current_win( * - 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: * Highlight groups as a map from group name to a highlight definition * map as in `nvim_set_hl()`, or only a single highlight definition map * if requested by name or id. - * - * Note: - * When the `link` attribute is defined in the highlight definition map, - * other attributes will not be taking effect (see `:hi-link`). */ export function nvim_get_hl( denops: Denops, @@ -710,6 +537,27 @@ export function nvim_get_hl_id_by_name( return denops.call("nvim_get_hl_id_by_name", ...args); } +/** + * Gets the active highlight namespace. + * + * Parameters: + * - **{opts}** Optional parameters + * - winid: (number) `window-ID` for retrieving a window's + * highlight namespace. A value of -1 is returned when + * `nvim_win_set_hl_ns()` has not been called for the window + * (or was called with a namespace of -1). + * + * Return: + * Namespace id, or -1 + */ +export function nvim_get_hl_ns(denops: Denops, opts: unknown): Promise; +export function nvim_get_hl_ns( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim_get_hl_ns", ...args); +} + /** * Gets a list of global (non-buffer-local) `mapping` definitions. * @@ -732,13 +580,14 @@ export function nvim_get_keymap( } /** - * Return a tuple (row, col, buffer, buffername) representing the position of - * the uppercase/file named mark. See `mark-motions`. + * 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` * * Note: - * fails with error if a lowercase or buffer local named mark is used. + * - Lowercase name (or other buffer-local mark) is an error. * * Parameters: * - **{name}** Mark name @@ -768,11 +617,11 @@ export function nvim_get_mark( * Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for * input. * - * Return: - * Dictionary { "mode": String, "blocking": Boolean } - * * Attributes: * `api-fast` + * + * Return: + * Dictionary { "mode": String, "blocking": Boolean } */ export function nvim_get_mode(denops: Denops): Promise; export function nvim_get_mode( @@ -887,12 +736,10 @@ export function nvim_get_vvar( * On execution error: does not fail, but updates v:errmsg. * * Note: - * `keycodes` like `` are translated, so `"<"` is special. To input a + * - `keycodes` like `` are translated, so `"<"` is special. To input a * literal `"<"`, send ``. - * - * Note: - * For mouse events use `nvim_input_mouse()`. The pseudokey form - * `""` is deprecated since `api-level` 6. + * - For mouse events use `nvim_input_mouse()`. The pseudokey form + * `` is deprecated since `api-level` 6. * * Attributes: * `api-fast` @@ -919,10 +766,10 @@ export function nvim_input( * processed soon by the event loop. * * Note: - * Currently this doesn't support "scripting" multiple mouse events by + * - Currently this doesn't support "scripting" multiple mouse events by * calling it multiple times in a loop: the intermediate mouse positions * will be ignored. It should be used to implement real-time mouse input - * in a GUI. The deprecated pseudokey form (`""`) of + * in a GUI. The deprecated pseudokey form (``) of * `nvim_input()` has the same limitation. * * Attributes: @@ -930,7 +777,7 @@ export function nvim_input( * * Parameters: * - **{button}** Mouse button: one of "left", "right", "middle", "wheel", - * "move". + * "move", "x1", "x2". * - **{action}** For ordinary buttons, one of "press", "drag", "release". * For the wheel, one of "up", "down", "left", "right". * Ignored for "move". @@ -991,7 +838,7 @@ export function nvim_list_chans( } /** - * Gets the paths contained in 'runtimepath'. + * Gets the paths contained in `runtime-search-path`. * * Return: * List of paths @@ -1107,15 +954,20 @@ export function nvim_notify( * `nvim_chan_send()` can be called immediately to process sequences in a * virtual terminal having the intended size. * + * Attributes: + * not allowed when `textlock` is active + * * Parameters: * - **{buffer}** the buffer to use (expected to be empty) * - **{opts}** Optional parameters. - * - on_input: lua callback for input sent, i e keypresses in + * - 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] + * callback however. `["input", term, bufnr, data]` + * - force_crlf: (boolean, default true) Convert "\n" to + * "\r\n". * * Return: * Channel id, or 0 on error @@ -1165,13 +1017,13 @@ export function nvim_out_write( * - **{data}** Multiline input. May be binary (containing NUL bytes). * - **{crlf}** Also break lines at CR and CRLF. * - **{phase}** -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) * * Return: - * * - true: Client may continue pasting. * - false: Client must cancel the paste. */ @@ -1290,7 +1142,7 @@ export function nvim_select_popupmenu_item( * using that library later identifies itself. * * Note: - * "Something is better than nothing". You don't need to include all the + * - "Something is better than nothing". You don't need to include all the * fields. * * Attributes: @@ -1310,7 +1162,11 @@ export function nvim_select_popupmenu_item( * - **{type}** Must be one of the following values. Client libraries * should default to "remote" unless overridden by the * user. - * - "remote" remote client connected to Nvim. + * - "remote" remote client connected "Nvim flavored" + * MessagePack-RPC (responses must be in reverse order of + * requests). `msgpack-rpc` + * - "msgpack-rpc" remote client connected to Nvim via + * fully MessagePack-RPC compliant protocol. * - "ui" gui frontend * - "embedder" application using Nvim as a component (for * example, IDE/editor implementing a vim mode). @@ -1356,7 +1212,7 @@ export function nvim_set_client_info( * Sets the current buffer. * * Attributes: - * not allowed when `textlock` is active + * not allowed when `textlock` is active or in the `cmdwin` * * Parameters: * - **{buffer}** Buffer handle @@ -1413,7 +1269,7 @@ export function nvim_set_current_line( * Sets the current tabpage. * * Attributes: - * not allowed when `textlock` is active + * not allowed when `textlock` is active or in the `cmdwin` * * Parameters: * - **{tabpage}** Tabpage handle @@ -1433,7 +1289,7 @@ export function nvim_set_current_tabpage( * Sets the current window. * * Attributes: - * not allowed when `textlock` is active + * not allowed when `textlock` is active or in the `cmdwin` * * Parameters: * - **{window}** Window handle @@ -1453,19 +1309,15 @@ export function nvim_set_current_win( * Sets a highlight group. * * Note: - * Unlike the `:highlight` command which can update a highlight group, + * - Unlike the `:highlight` command which can update a highlight group, * this function completely replaces the definition. For example: * `nvim_set_hl(0, 'Visual', {})` will clear the highlight group * 'Visual'. - * - * Note: - * The fg and bg keys also accept the string values `"fg"` or `"bg"` + * - The fg and bg keys also accept the string values `"fg"` or `"bg"` * which act as aliases to the corresponding foreground and background * values of the Normal group. If the Normal group has not been defined, * using these values results in an error. - * - * Note: - * If `link` is used in combination with other attributes; only the + * - If `link` is used in combination with other attributes; only the * `link` will take effect (see `:hi-link`). * * Parameters: @@ -1476,9 +1328,9 @@ export function nvim_set_current_win( * activate them. * - **{name}** Highlight group name, e.g. "ErrorMsg" * - **{val}** 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 @@ -1499,6 +1351,8 @@ export function nvim_set_current_win( * - 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. */ export function nvim_set_hl( denops: Denops, @@ -1564,24 +1418,26 @@ export function nvim_set_hl_ns_fast( * Unlike `:map`, leading/trailing whitespace is accepted as part of the * **{lhs}** or **{rhs}**. Empty **{rhs}** is ``. `keycodes` are replaced as usual. * - * Example: >vim + * Example: + * * call nvim_set_keymap('n', ' ', '', {'nowait': v:true}) - * < * - * is equivalent to: >vim - * nmap `` `` `` - * < + * is equivalent to: + * + * nmap * * Parameters: - * - **{mode}** Mode short-name (map command prefix: "n", "i", "v", "x", …) or - * "!" for `:map!`, or empty string for `:map`. + * - **{mode}** 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 * - **{lhs}** Left-hand-side `{lhs}` of the mapping. * - **{rhs}** Right-hand-side `{rhs}` of the mapping. * - **{opts}** Optional parameters map: Accepts all `:map-arguments` as keys * except ``, values are booleans (default false). Also: - * - "noremap" non-recursive mapping `:noremap` + * - "noremap" disables `recursive_mapping`, like `:noremap` * - "desc" human-readable description. - * - "callback" Lua function called when the mapping is executed. + * - "callback" Lua function called in place of **{rhs}**. * - "replace_keycodes" (boolean) When "expr" is true, replace * keycodes in the resulting string (see * `nvim_replace_termcodes()`). Returning nil from the Lua @@ -1698,13 +1554,229 @@ export function nvim_unsubscribe( } /** - * Calls a VimL `Dictionary-function` with the given arguments. + * EXPERIMENTAL: this API may change in the future. + * + * Sets info for the completion item at the given index. If the info text was + * shown in a window, returns the window and buffer ids, or empty dict if not + * shown. + * + * Parameters: + * - **{index}** Completion candidate index + * - **{opts}** Optional parameters. + * - info: (string) info text. + * + * Return: + * Dictionary containing these keys: + * - winid: (number) floating window id + * - bufnr: (number) buffer id in floating window + */ +export function nvim__complete_set( + denops: Denops, + index: unknown, + opts: unknown, +): Promise; +export function nvim__complete_set( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__complete_set", ...args); +} + +/** + * Find files in runtime directories + * + * Attributes: + * `api-fast` + * + * Parameters: + * - **{pat}** pattern of files to search for + * - **{all}** whether to return all matches or only the first + * - **{opts}** is_lua: only search Lua subdirs + * + * Return: + * list of absolute paths to the found files + */ +export function nvim__get_runtime( + denops: Denops, + pat: unknown, + all: unknown, + opts: unknown, +): Promise; +export function nvim__get_runtime( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__get_runtime", ...args); +} + +/** + * Returns object given as argument. + * + * This API function is used for testing. One should not rely on its presence + * in plugins. + * + * Parameters: + * - **{obj}** Object to return. + * + * Return: + * its argument. + */ +export function nvim__id(denops: Denops, obj: unknown): Promise; +export function nvim__id(denops: Denops, ...args: unknown[]): Promise { + return denops.call("nvim__id", ...args); +} + +/** + * Returns array given as argument. + * + * This API function is used for testing. One should not rely on its presence + * in plugins. + * + * Parameters: + * - **{arr}** Array to return. + * + * Return: + * its argument. + */ +export function nvim__id_array(denops: Denops, arr: unknown): Promise; +export function nvim__id_array( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__id_array", ...args); +} + +/** + * Returns dictionary given as argument. + * + * This API function is used for testing. One should not rely on its presence + * in plugins. + * + * Parameters: + * - **{dct}** Dictionary to return. + * + * Return: + * its argument. + */ +export function nvim__id_dictionary( + denops: Denops, + dct: unknown, +): Promise; +export function nvim__id_dictionary( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__id_dictionary", ...args); +} + +/** + * Returns floating-point value given as argument. + * + * This API function is used for testing. One should not rely on its presence + * in plugins. + * + * Parameters: + * - **{flt}** Value to return. + * + * Return: + * its argument. + */ +export function nvim__id_float(denops: Denops, flt: unknown): Promise; +export function nvim__id_float( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__id_float", ...args); +} + +/** + * NB: if your UI doesn't use hlstate, this will not return hlstate first + * time. + */ +export function nvim__inspect_cell( + denops: Denops, + grid: unknown, + row: unknown, + col: unknown, +): Promise; +export function nvim__inspect_cell( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__inspect_cell", ...args); +} + +/** + * For testing. The condition in schar_cache_clear_if_full is hard to reach, + * so this function can be used to force a cache clear in a test. + */ +export function nvim__invalidate_glyph_cache(denops: Denops): Promise; +export function nvim__invalidate_glyph_cache( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__invalidate_glyph_cache", ...args); +} + +/** + * EXPERIMENTAL: this API may change in the future. * - * On execution error: fails with VimL error, updates v:errmsg. + * Instruct Nvim to redraw various components. * * Parameters: - * - **{dict}** Dictionary, or String evaluating to a VimL `self` dict - * - **{fn}** Name of the function defined on the VimL dict + * - **{opts}** Optional parameters. + * - win: Target a specific `window-ID` as described below. + * - buf: Target a specific buffer number as described below. + * - flush: Update the screen with pending updates. + * - valid: When present mark `win`, `buf`, or all windows for + * redraw. When `true`, only redraw changed lines (useful for + * decoration providers). When `false`, forcefully redraw. + * - range: Redraw a range in `buf`, the buffer in `win` or the + * current buffer (useful for decoration providers). Expects a + * tuple `[first, last]` with the first and last line number of + * the range, 0-based end-exclusive `api-indexing`. + * - cursor: Immediately update cursor position on the screen in + * `win` or the current window. + * - statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or + * all windows. + * - statusline: Redraw the 'statusline' in `buf`, `win` or all + * windows. + * - winbar: Redraw the 'winbar' in `buf`, `win` or all windows. + * - tabline: Redraw the 'tabline'. + * + * See also: + * - `:redraw` + */ +export function nvim__redraw(denops: Denops, opts: unknown): Promise; +export function nvim__redraw( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__redraw", ...args); +} + +/** + * Gets internal stats. + * + * Return: + * Map of various internal stats. + */ +export function nvim__stats(denops: Denops): Promise; +export function nvim__stats( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__stats", ...args); +} + +/** + * Calls a Vimscript `Dictionary-function` with the given arguments. + * + * On execution error: fails with Vimscript error, updates v:errmsg. + * + * Parameters: + * - **{dict}** Dictionary, or String evaluating to a Vimscript `self` dict + * - **{fn}** Name of the function defined on the Vimscript dict * - **{args}** Function arguments packed in an Array * * Return: @@ -1724,9 +1796,9 @@ export function nvim_call_dict_function( } /** - * Calls a VimL function with the given arguments. + * Calls a Vimscript function with the given arguments. * - * On execution error: fails with VimL error, updates v:errmsg. + * On execution error: fails with Vimscript error, updates v:errmsg. * * Parameters: * - **{fn}** Function to call @@ -1750,7 +1822,7 @@ export function nvim_call_function( /** * Executes an Ex command. * - * On execution error: fails with VimL error, updates v:errmsg. + * 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 @@ -1773,13 +1845,13 @@ export function nvim_command( } /** - * Evaluates a VimL `expression`. Dictionaries and Lists are recursively + * Evaluates a Vimscript `expression`. Dictionaries and Lists are recursively * expanded. * - * On execution error: fails with VimL error, updates v:errmsg. + * On execution error: fails with Vimscript error, updates v:errmsg. * * Parameters: - * - **{expr}** VimL expression string + * - **{expr}** Vimscript expression string * * Return: * Evaluation result or expanded object @@ -1799,7 +1871,7 @@ export function nvim_eval( * Unlike `nvim_command()` this function supports heredocs, script-scope * (s:), etc. * - * On execution error: fails with VimL error, updates v:errmsg. + * On execution error: fails with Vimscript error, updates v:errmsg. * * Parameters: * - **{src}** Vimscript code @@ -1829,7 +1901,7 @@ export function nvim_exec2( } /** - * Parse a VimL expression. + * Parse a Vimscript expression. * * Attributes: * `api-fast` @@ -1844,9 +1916,9 @@ export function nvim_exec2( * 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". + * - "m" to parse like for `":echo"`. + * - "E" to parse like for `"=``"`. + * - empty string for "``:call". * - "lm" to parse for ":let". * - **{highlight}** If true, return value will also include "highlight" key * containing array of 4-tuples (arrays) (Integer, Integer, @@ -1856,25 +1928,23 @@ export function nvim_exec2( * region [start_col, end_col)). * * Return: - * * - AST: top-level dictionary with these keys: * - "error": Dictionary with error, present only if parser saw some * error. Contains the following keys: * - "message": String, error message in printf format, translated. * Must contain exactly one "%.*s". * - "arg": String, error message argument. - * * - "len": Amount of bytes successfully parsed. With flags equal to "" - * that should be equal to the length of expr string. (“Successfully - * parsed” here means “participated in AST creation”, not “till the - * first error”.) + * that should be equal to the length of expr string. ("Successfully + * parsed" here means "participated in AST creation", not "till the + * first error".) * - "ast": AST, either nil or a dictionary with these keys: * - "type": node type, one of the value names from ExprASTNodeType * stringified without "kExprNode" prefix. - * - "start": a pair [line, column] describing where node is + * - "start": a pair `[line, column]` describing where node is * "started" where "line" is always 0 (will not be 0 if you will be - * using nvim_parse_viml() on e.g. ":let", but that is not present - * yet). Both elements are Integers. + * using this API on e.g. ":let", but that is not present yet). + * Both elements are Integers. * - "len": “length” of the node. This and "start" are there for * debugging purposes primary (debugging parser and providing debug * information). @@ -1882,7 +1952,6 @@ export function nvim_exec2( * is zero, one or two children, key will not be present if node * has no children. Maximum number of children may be found in * node_maxchildren array. - * * - Local values (present only for certain nodes): * - "scope": a single Integer, specifies scope for "Option" and * "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope @@ -1924,7 +1993,7 @@ export function nvim_parse_expression( * Creates a buffer-local command `user-commands`. * * Parameters: - * - **{buffer}** Buffer handle, or 0 for current buffer. + * - **{buffer}** Buffer handle, or 0 for current buffer. * * See also: * - nvim_create_user_command @@ -2002,7 +2071,7 @@ export function nvim_buf_get_commands( * example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do * `vim.cmd.bdelete(2)`. * - * On execution error: fails with VimL error, updates v:errmsg. + * On execution error: fails with Vimscript error, updates v:errmsg. * * Parameters: * - **{cmd}** Command to execute. Must be a Dictionary that can contain the @@ -2035,11 +2104,11 @@ export function nvim_cmd(denops: Denops, ...args: unknown[]): Promise { * * For Lua usage see `lua-guide-commands-create`. * - * Example: >vim - * :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) - * :SayHello - * Hello world! - * < + * Example: + * + * :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) + * :SayHello + * Hello world! * * Parameters: * - **{name}** Name of the new user command. Must begin with an uppercase @@ -2052,8 +2121,8 @@ export function nvim_cmd(denops: Denops, ...args: unknown[]): Promise { * - 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 `` * - line1: (number) The starting line of the command range @@ -2123,6 +2192,9 @@ export function nvim_del_user_command( * * Return: * Map of maps describing commands. + * + * See also: + * - `nvim_get_all_options_info()` */ export function nvim_get_commands( denops: Denops, @@ -2150,11 +2222,10 @@ export function nvim_get_commands( * Return: * Dictionary containing command information, with these keys: * - cmd: (string) Command name. - * - range: (array) (optional) Command range (`` ``). - * Omitted if command doesn't accept a range. Otherwise, has no - * elements if no range was specified, one element if only a single - * range item was specified, or two elements if both range items were - * specified. + * - range: (array) (optional) Command range (`` ``). Omitted + * if command doesn't accept a range. Otherwise, has no elements if no + * range was specified, one element if only a single range item was + * specified, or two elements if both range items were specified. * - count: (number) (optional) Command ``. Omitted if command * cannot take a count. * - reg: (string) (optional) Command ``. Omitted if command @@ -2173,13 +2244,11 @@ export function nvim_get_commands( * - bar: (boolean) The "|" character is treated as a command separator * and the double quote character (") is treated as the start of a * comment. - * * - mods: (dictionary) `:command-modifiers`. * - filter: (dictionary) `:filter`. * - pattern: (string) Filter pattern. Empty string if there is no * filter. * - force: (boolean) Whether filter is inverted or not. - * * - silent: (boolean) `:silent`. * - emsg_silent: (boolean) `:silent!`. * - unsilent: (boolean) `:unsilent`. @@ -2188,78 +2257,34 @@ export function nvim_get_commands( * - browse: (boolean) `:browse`. * - confirm: (boolean) `:confirm`. * - hide: (boolean) `:hide`. - * - horizontal: (boolean) `:horizontal`. - * - keepalt: (boolean) `:keepalt`. - * - keepjumps: (boolean) `:keepjumps`. - * - keepmarks: (boolean) `:keepmarks`. - * - keeppatterns: (boolean) `:keeppatterns`. - * - lockmarks: (boolean) `:lockmarks`. - * - noswapfile: (boolean) `:noswapfile`. - * - tab: (integer) `:tab`. -1 when omitted. - * - verbose: (integer) `:verbose`. -1 when omitted. - * - vertical: (boolean) `:vertical`. - * - split: (string) Split modifier string, is an empty string when - * there's no split modifier. If there is a split modifier it can be - * one of: - * - "aboveleft": `:aboveleft`. - * - "belowright": `:belowright`. - * - "topleft": `:topleft`. - * - "botright": `:botright`. - */ -export function nvim_parse_cmd( - denops: Denops, - str: unknown, - opts: unknown, -): Promise; -export function nvim_parse_cmd( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_parse_cmd", ...args); -} - -/** - * Gets a buffer option value - * - * Parameters: - * - **{buffer}** Buffer handle, or 0 for current buffer - * - **{name}** Option name - * - * Return: - * Option value - */ -export function nvim_buf_get_option( - denops: Denops, - buffer: unknown, - name: unknown, -): Promise; -export function nvim_buf_get_option( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_buf_get_option", ...args); -} - -/** - * Sets a buffer option value. Passing `nil` as value deletes the option - * (only works if there's a global fallback) - * - * Parameters: - * - **{buffer}** Buffer handle, or 0 for current buffer - * - **{name}** Option name - * - **{value}** Option value + * - horizontal: (boolean) `:horizontal`. + * - keepalt: (boolean) `:keepalt`. + * - keepjumps: (boolean) `:keepjumps`. + * - keepmarks: (boolean) `:keepmarks`. + * - keeppatterns: (boolean) `:keeppatterns`. + * - lockmarks: (boolean) `:lockmarks`. + * - noswapfile: (boolean) `:noswapfile`. + * - tab: (integer) `:tab`. -1 when omitted. + * - verbose: (integer) `:verbose`. -1 when omitted. + * - vertical: (boolean) `:vertical`. + * - split: (string) Split modifier string, is an empty string when + * there's no split modifier. If there is a split modifier it can be + * one of: + * - "aboveleft": `:aboveleft`. + * - "belowright": `:belowright`. + * - "topleft": `:topleft`. + * - "botright": `:botright`. */ -export function nvim_buf_set_option( +export function nvim_parse_cmd( denops: Denops, - buffer: unknown, - name: unknown, - value: unknown, + str: unknown, + opts: unknown, ): Promise; -export function nvim_buf_set_option( +export function nvim_parse_cmd( denops: Denops, ...args: unknown[] ): Promise { - return denops.call("nvim_buf_set_option", ...args); + return denops.call("nvim_parse_cmd", ...args); } /** @@ -2270,6 +2295,9 @@ export function nvim_buf_set_option( * * Return: * dictionary of all options + * + * See also: + * - `nvim_get_commands()` */ export function nvim_get_all_options_info(denops: Denops): Promise; export function nvim_get_all_options_info( @@ -2279,26 +2307,6 @@ export function nvim_get_all_options_info( return denops.call("nvim_get_all_options_info", ...args); } -/** - * Gets the global value of an option. - * - * Parameters: - * - **{name}** Option name - * - * Return: - * Option value (global) - */ -export function nvim_get_option( - denops: Denops, - name: unknown, -): Promise; -export function nvim_get_option( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_get_option", ...args); -} - /** * Gets the option information for one option from arbitrary buffer or window * @@ -2379,25 +2387,6 @@ export function nvim_get_option_value( return denops.call("nvim_get_option_value", ...args); } -/** - * Sets the global value of an option. - * - * Parameters: - * - **{name}** Option name - * - **{value}** New option value - */ -export function nvim_set_option( - denops: Denops, - name: unknown, - value: unknown, -): Promise; -export function nvim_set_option( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_set_option", ...args); -} - /** * 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 @@ -2427,58 +2416,18 @@ export function nvim_set_option_value( return denops.call("nvim_set_option_value", ...args); } -/** - * Gets a window option value - * - * Parameters: - * - **{window}** Window handle, or 0 for current window - * - **{name}** Option name - * - * Return: - * Option value - */ -export function nvim_win_get_option( - denops: Denops, - window: unknown, - name: unknown, -): Promise; -export function nvim_win_get_option( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_win_get_option", ...args); -} - -/** - * Sets a window option value. Passing `nil` as value deletes the option - * (only works if there's a global fallback) - * - * Parameters: - * - **{window}** Window handle, or 0 for current window - * - **{name}** Option name - * - **{value}** Option value - */ -export function nvim_win_set_option( - denops: Denops, - window: unknown, - name: unknown, - value: unknown, -): Promise; -export function nvim_win_set_option( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("nvim_win_set_option", ...args); -} - /** * Activates buffer-update events on a channel, or as Lua callbacks. * - * Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua - * events = {} - * vim.api.nvim_buf_attach(0, false, { - * on_lines=function(...) table.insert(events, **{...}**) end}) - * < + * Example (Lua): capture buffer updates in a global `events` variable (use + * "vim.print(events)" to see its contents): + * + * events = {} + * vim.api.nvim_buf_attach(0, false, { + * on_lines = function(...) + * table.insert(events, {...}) + * end, + * }) * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer @@ -2488,7 +2437,8 @@ export function nvim_win_set_option( * will be `nvim_buf_changedtick_event`. Not for Lua * callbacks. * - **{opts}** 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 @@ -2498,10 +2448,10 @@ export function nvim_win_set_option( * - 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 + * - 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 a truthy value + * (not `false` or `nil`) to detach. Args: * - the string "bytes" * - buffer handle * - b:changedtick @@ -2509,28 +2459,28 @@ export function nvim_win_set_option( * - 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 * 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. @@ -2567,20 +2517,19 @@ export function nvim_buf_attach( * a temporary scratch window (called the "autocmd window" for historical * reasons) will be used. * - * This is useful e.g. to call vimL functions that only work with the current - * buffer/window currently, like `termopen()`. + * This is useful e.g. to call Vimscript functions that only work with the + * current buffer/window currently, like `termopen()`. * * Attributes: * Lua `vim.api` only * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer - * - **{fun}** Function to call inside the buffer (currently lua callable + * - **{fun}** Function to call inside the buffer (currently Lua callable * only) * * Return: - * Return value of function. NB: will deepcopy lua values currently, use - * upvalues to send lua references in and out. + * Return value of function. */ export function nvim_buf_call( denops: Denops, @@ -2620,7 +2569,7 @@ export function nvim_buf_del_keymap( * Deletes a named mark in the buffer. See `mark-motions`. * * Note: - * only deletes marks set in the buffer, if the mark is not set in the + * - only deletes marks set in the buffer, if the mark is not set in the * buffer it will return false. * * Parameters: @@ -2669,7 +2618,7 @@ export function nvim_buf_del_var( * Deletes the buffer. See `:bwipeout` * * Attributes: - * not allowed when `textlock` is active + * not allowed when `textlock` is active or in the `cmdwin` * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer @@ -2741,8 +2690,8 @@ export function nvim_buf_get_changedtick( * Gets a list of buffer-local `mapping` definitions. * * Parameters: - * - **{mode}** Mode short-name ("n", "i", "v", ...) * - **{buffer}** Buffer handle, or 0 for current buffer + * - **{mode}** Mode short-name ("n", "i", "v", ...) * * Return: * Array of `maparg()`-like dictionaries describing mappings. The @@ -2794,7 +2743,8 @@ export function nvim_buf_get_lines( } /** - * Returns a tuple (row,col) representing the position of the named mark. See + * 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` @@ -2958,7 +2908,7 @@ export function nvim_buf_is_loaded( * Checks if a buffer is valid. * * Note: - * Even if a buffer is valid it may have been unloaded. See `api-buffer` + * - Even if a buffer is valid it may have been unloaded. See `api-buffer` * for more info about unloaded buffers. * * Parameters: @@ -3070,7 +3020,7 @@ export function nvim_buf_set_lines( * Marks are (1,0)-indexed. `api-indexing` * * Note: - * Passing 0 as line deletes the mark + * - Passing 0 as line deletes the mark * * Parameters: * - **{buffer}** Buffer to set the mark on @@ -3102,7 +3052,7 @@ export function nvim_buf_set_mark( } /** - * Sets the full file name for a buffer + * Sets the full file name for a buffer, like `:file_f` * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer @@ -3130,13 +3080,18 @@ export function nvim_buf_set_name( * 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. * + * Prefer `nvim_put()` if you want to insert text at the cursor position. + * + * Attributes: + * not allowed when `textlock` is active + * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer * - {start_row} First line index @@ -3147,6 +3102,7 @@ export function nvim_buf_set_name( * * See also: * - `nvim_buf_set_lines()` + * - `nvim_put()` */ export function nvim_buf_set_text( denops: Denops, @@ -3322,28 +3278,36 @@ export function nvim_buf_get_extmark_by_id( * * 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: >lua - * vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) - * vim.api.nvim_buf_get_extmarks(0, my_ns, **{0,0}**, **{-1,-1}**, {}) - * < + * respectively, thus the following are equivalent: + * + * vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + * vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) * * If `end` is less than `start`, traversal works backwards. (Useful with * `limit`, to get the first marks prior to a given position.) * - * Example: >lua - * local api = vim.api - * local pos = api.nvim_win_get_cursor(0) - * local ns = api.nvim_create_namespace('my-plugin') - * -- Create new extmark at line 1, column 1. - * local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) - * -- Create new extmark at line 3, column 1. - * local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) - * -- Get extmarks only from line 3. - * local ms = api.nvim_buf_get_extmarks(0, ns, **{2,0}**, **{2,0}**, {}) - * -- Get all marks in this buffer + namespace. - * local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) - * print(vim.inspect(ms)) - * < + * 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: + * + * local api = vim.api + * local pos = api.nvim_win_get_cursor(0) + * local ns = api.nvim_create_namespace('my-plugin') + * -- Create new extmark at line 1, column 1. + * local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) + * -- Create new extmark at line 3, column 1. + * local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) + * -- Get extmarks only from line 3. + * local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) + * -- Get all marks in this buffer + namespace. + * local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) + * vim.print(ms) * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer @@ -3359,11 +3323,13 @@ export function nvim_buf_get_extmark_by_id( * - 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: - * List of [extmark_id, row, col] tuples in "traversal order". + * List of `[extmark_id, row, col]` tuples in "traversal order". */ export function nvim_buf_get_extmarks( denops: Denops, @@ -3392,6 +3358,11 @@ export function nvim_buf_get_extmarks( * 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 + * range (no highlighting). + * * Parameters: * - **{buffer}** Buffer handle, or 0 for current buffer * - {ns_id} Namespace id from `nvim_create_namespace()` @@ -3407,7 +3378,7 @@ export function nvim_buf_get_extmarks( * 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 @@ -3415,33 +3386,39 @@ export function nvim_buf_get_extmarks( * 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) + * - "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) + * 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 due to horizontal scroll - * 'nowrap' + * 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. - * + * 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. + * 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. @@ -3456,28 +3433,32 @@ export function nvim_buf_get_extmarks( * 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. - * - priority: a priority value for the highlight group or sign - * attribute. For example treesitter highlighting uses a - * value of 100. + * - 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. 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`. @@ -3489,6 +3470,11 @@ export function nvim_buf_get_extmarks( * 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 (EXPERIMENTAL) enables "scoping" for the + * extmark. See `nvim__win_add_ns()` * * Return: * Id of the created/updated extmark @@ -3552,14 +3538,14 @@ export function nvim_get_namespaces( /** * Set or change decoration provider for a `namespace` * - * This is a very general purpose interface for having lua callbacks being + * 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 ). + * redraw). * * Note: this function should not be called often. Rather, the callbacks * themselves can be used to throttle unneeded callbacks. the `on_start` @@ -3571,27 +3557,41 @@ export function nvim_get_namespaces( * 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 expliticly + * 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. + * * Attributes: * Lua `vim.api` only * * Parameters: * - {ns_id} Namespace id from `nvim_create_namespace()` * - **{opts}** 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_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] - * - 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] */ export function nvim_set_decoration_provider( denops: Denops, @@ -3605,6 +3605,77 @@ export function nvim_set_decoration_provider( return denops.call("nvim_set_decoration_provider", ...args); } +/** + * EXPERIMENTAL: this API will change in the future. + * + * Scopes a namespace to the a window, so extmarks in the namespace will be + * active only in the given window. + * + * Parameters: + * - **{window}** Window handle, or 0 for current window + * - {ns_id} Namespace + * + * Return: + * true if the namespace was added, else false + */ +export function nvim__win_add_ns( + denops: Denops, + window: unknown, + ns_id: unknown, +): Promise; +export function nvim__win_add_ns( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__win_add_ns", ...args); +} + +/** + * EXPERIMENTAL: this API will change in the future. + * + * Unscopes a namespace (un-binds it from the given scope). + * + * Parameters: + * - **{window}** Window handle, or 0 for current window + * - {ns_id} the namespace to remove + * + * Return: + * true if the namespace was removed, else false + */ +export function nvim__win_del_ns( + denops: Denops, + window: unknown, + ns_id: unknown, +): Promise; +export function nvim__win_del_ns( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__win_del_ns", ...args); +} + +/** + * EXPERIMENTAL: this API will change in the future. + * + * Gets the namespace scopes for a given window. + * + * Parameters: + * - **{window}** Window handle, or 0 for current window + * + * Return: + * a list of namespaces ids + */ +export function nvim__win_get_ns( + denops: Denops, + window: unknown, +): Promise; +export function nvim__win_get_ns( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim__win_get_ns", ...args); +} + /** * Calls a function with window as temporary current window. * @@ -3613,12 +3684,11 @@ export function nvim_set_decoration_provider( * * Parameters: * - **{window}** Window handle, or 0 for current window - * - **{fun}** Function to call inside the window (currently lua callable + * - **{fun}** Function to call inside the window (currently Lua callable * only) * * Return: - * Return value of function. NB: will deepcopy lua values currently, use - * upvalues to send lua references in and out. + * Return value of function. * * See also: * - `win_execute()` @@ -3709,6 +3779,9 @@ export function nvim_win_get_buf( * * Return: * (row, col) tuple + * + * See also: + * - `getcurpos()` */ export function nvim_win_get_cursor( denops: Denops, @@ -3957,7 +4030,7 @@ export function nvim_win_set_height( * This takes precedence over the 'winhighlight' option. * * Parameters: - * - {ns_id} the namespace to use + * - {ns_id} the namespace to use */ export function nvim_win_set_hl_ns( denops: Denops, @@ -4012,6 +4085,52 @@ export function nvim_win_set_width( return denops.call("nvim_win_set_width", ...args); } +/** + * 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()`. + * + * Parameters: + * - **{window}** Window handle, or 0 for current window. + * - **{opts}** 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. + * + * Return: + * Dictionary containing text height information, with these keys: + * - all: The total number of screen lines occupied by the range. + * - fill: The number of diff filler or virtual lines among them. + * + * See also: + * - `virtcol()` for text width. + */ +export function nvim_win_text_height( + denops: Denops, + window: unknown, + opts: unknown, +): Promise; +export function nvim_win_text_height( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim_win_text_height", ...args); +} + /** * Removes a tab-scoped (t:) variable * @@ -4155,8 +4274,27 @@ export function nvim_tabpage_set_var( } /** - * Clear all autocommands that match the corresponding **{opts}**. To delete a - * particular autocmd, see `nvim_del_autocmd()`. + * Sets the current window in a tabpage + * + * Parameters: + * - **{tabpage}** Tabpage handle, or 0 for current tabpage + * - **{win}** Window handle, must already belong to **{tabpage}** + */ +export function nvim_tabpage_set_win( + denops: Denops, + tabpage: unknown, + win: unknown, +): Promise; +export function nvim_tabpage_set_win( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim_tabpage_set_win", ...args); +} + +/** + * Clears all autocommands selected by **{opts}**. To delete autocmds see + * `nvim_del_autocmd()`. * * Parameters: * - **{opts}** Parameters @@ -4164,22 +4302,19 @@ export function nvim_tabpage_set_var( * - 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. + * - NOTE: If not passed, will only delete autocmds not in any + * group. */ export function nvim_clear_autocmds( denops: Denops, @@ -4195,11 +4330,11 @@ export function nvim_clear_autocmds( /** * Create or get an autocommand group `autocmd-groups`. * - * To get an existing group id, do: >lua + * To get an existing group id, do: + * * local id = vim.api.nvim_create_augroup("MyGroup", { * clear = false * }) - * < * * Parameters: * - **{name}** String: The name of the group @@ -4226,28 +4361,30 @@ export function nvim_create_augroup( } /** - * 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: * - * Example using Lua callback: >lua * vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { * pattern = {"*.c", "*.h"}, * callback = function(ev) - * print(string.format('event fired: s', vim.inspect(ev))) + * print(string.format('event fired: %s', vim.inspect(ev))) * end * }) - * < * - * Example using an Ex command as the handler: >lua + * Example using an Ex command as the handler: + * * vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { * pattern = {"*.c", "*.h"}, * command = "echo 'Entering a C or C++ file'", * }) - * < * - * Note: `pattern` is NOT automatically expanded (unlike with `:autocmd`), thus names like - * "$HOME" and `"~"` must be expanded explicitly: >lua - * pattern = vim.fn.expand(`"~"`) .. "/some/path/*.py" - * < + * Note: `pattern` is NOT automatically expanded (unlike with `:autocmd`), + * thus names like "$HOME" and `"~"` must be expanded explicitly: + * + * pattern = vim.fn.expand("~") .. "/some/path/*.py" * * Parameters: * - **{event}** (string|array) Event(s) that will trigger the handler @@ -4264,9 +4401,10 @@ export function nvim_create_augroup( * 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 one argument, a table with these keys: + * * - id: (number) autocommand id * - event: (string) name of the triggered event * `autocmd-events` @@ -4276,7 +4414,6 @@ export function nvim_create_augroup( * - 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 @@ -4355,15 +4492,10 @@ export function nvim_del_augroup_by_name( } /** - * Delete an autocommand by id. - * - * NOTE: Only autocommands created via the API have an id. + * Deletes an autocommand by id. * * Parameters: - * - **{id}** Integer The id returned by nvim_create_autocmd - * - * See also: - * - `nvim_create_autocmd()` + * - **{id}** Integer Autocommand id returned by `nvim_create_autocmd()` */ export function nvim_del_autocmd(denops: Denops, id: unknown): Promise; export function nvim_del_autocmd( @@ -4409,19 +4541,19 @@ export function nvim_exec_autocmds( /** * Get all autocommands that match the corresponding **{opts}**. * - * These examples will get autocommands matching ALL the given criteria: >lua - * -- Matches all criteria - * autocommands = vim.api.nvim_get_autocmds({ - * group = "MyGroup", - * event = {"BufEnter", "BufWinEnter"}, - * pattern = {"*.c", "*.h"} - * }) + * These examples will get autocommands matching ALL the given criteria: * - * -- All commands from one group - * autocommands = vim.api.nvim_get_autocmds({ - * group = "MyGroup", - * }) - * < + * -- Matches all criteria + * autocommands = vim.api.nvim_get_autocmds({ + * group = "MyGroup", + * event = {"BufEnter", "BufWinEnter"}, + * pattern = {"*.c", "*.h"} + * }) + * + * -- All commands from one group + * autocommands = vim.api.nvim_get_autocmds({ + * group = "MyGroup", + * }) * * NOTE: When multiple patterns or events are provided, it will find all the * autocommands that match any combination of them. @@ -4475,7 +4607,7 @@ export function nvim_get_autocmds( * list of UIs. `nvim_list_uis()` * * Note: - * If multiple UI clients are attached, the global screen dimensions + * - If multiple UI clients are attached, the global screen dimensions * degrade to the smallest client. E.g. if client A requests 80x40 but * client B requests 200x100, the global screen has size 80x40. * @@ -4572,7 +4704,7 @@ export function nvim_ui_pum_set_height( } /** - * Tells the nvim server if focus was gained or lost by the GUI. + * Tells the nvim server if focus was gained or lost by the GUI * * Attributes: * `RPC` only @@ -4589,8 +4721,6 @@ export function nvim_ui_set_focus( } /** - * TODO: Documentation - * * Attributes: * `RPC` only */ @@ -4607,8 +4737,33 @@ export function nvim_ui_set_option( } /** - * TODO: Documentation + * Tells Nvim when a terminal event has occurred * + * The following terminal events are supported: + * - "termresponse": The terminal sent an OSC or DCS response sequence to + * Nvim. The payload is the received response. Sets `v:termresponse` and + * fires `TermResponse`. + * + * Attributes: + * `RPC` only + * + * Parameters: + * - **{event}** Event name + * - **{value}** Event payload + */ +export function nvim_ui_term_event( + denops: Denops, + event: unknown, + value: unknown, +): Promise; +export function nvim_ui_term_event( + denops: Denops, + ...args: unknown[] +): Promise { + return denops.call("nvim_ui_term_event", ...args); +} + +/** * Attributes: * `RPC` only */ @@ -4656,9 +4811,9 @@ export function nvim_ui_try_resize_grid( * * View it in a nice human-readable format: * - * :lua print(vim.inspect(vim.fn.api_info())) + * lua vim.print(vim.fn.api_info()) */ -export function api_info(denops: Denops): Promise>; +export function api_info(denops: Denops): Promise; export function api_info(denops: Denops, ...args: unknown[]): Promise { return denops.call("api_info", ...args); } @@ -4677,7 +4832,7 @@ export function chanclose( denops: Denops, id: unknown, stream?: unknown, -): Promise; +): Promise; export function chanclose( denops: Denops, ...args: unknown[] @@ -4697,7 +4852,7 @@ export function chanclose( * newlines in an item will be sent as NUL. To send a final * newline, include a final empty string. Example: * - * :call chansend(id, ["abc", "123\n456", ""]) + * call chansend(id, ["abc", "123\n456", ""]) * * will send `"abc123456"`. * @@ -4709,7 +4864,7 @@ export function chansend( denops: Denops, id: unknown, data: unknown, -): Promise; +): Promise; export function chansend(denops: Denops, ...args: unknown[]): Promise { return denops.call("chansend", ...args); } @@ -4719,10 +4874,7 @@ export function chansend(denops: Denops, ...args: unknown[]): Promise { * from the top of the `context-stack` (see `context-dict`). * If **{index}** is not given, it is assumed to be 0 (i.e.: top). */ -export function ctxget( - denops: Denops, - index?: unknown, -): Promise>; +export function ctxget(denops: Denops, index?: unknown): Promise; export function ctxget(denops: Denops, ...args: unknown[]): Promise { return denops.call("ctxget", ...args); } @@ -4731,7 +4883,7 @@ export function ctxget(denops: Denops, ...args: unknown[]): Promise { * Pops and restores the `context` at the top of the * `context-stack`. */ -export function ctxpop(denops: Denops): Promise; +export function ctxpop(denops: Denops): Promise; export function ctxpop(denops: Denops, ...args: unknown[]): Promise { return denops.call("ctxpop", ...args); } @@ -4743,7 +4895,7 @@ export function ctxpop(denops: Denops, ...args: unknown[]): Promise { * which `context-types` to include in the pushed context. * Otherwise, all context types are included. */ -export function ctxpush(denops: Denops, types?: unknown): Promise; +export function ctxpush(denops: Denops, types?: unknown): Promise; export function ctxpush(denops: Denops, ...args: unknown[]): Promise { return denops.call("ctxpush", ...args); } @@ -4758,7 +4910,7 @@ export function ctxset( denops: Denops, context: unknown, index?: unknown, -): Promise; +): Promise; export function ctxset(denops: Denops, ...args: unknown[]): Promise { return denops.call("ctxset", ...args); } @@ -4766,7 +4918,7 @@ export function ctxset(denops: Denops, ...args: unknown[]): Promise { /** * Returns the size of the `context-stack`. */ -export function ctxsize(denops: Denops): Promise; +export function ctxsize(denops: Denops): Promise; export function ctxsize(denops: Denops, ...args: unknown[]): Promise { return denops.call("ctxsize", ...args); } @@ -4860,7 +5012,7 @@ export function dictwatcherdel( * will not be equal to some other `id()`: new containers may * reuse identifiers of the garbage-collected ones. */ -export function id(denops: Denops, expr: unknown): Promise; +export function id(denops: Denops, expr: unknown): Promise; export function id(denops: Denops, ...args: unknown[]): Promise { return denops.call("id", ...args); } @@ -4868,7 +5020,7 @@ export function id(denops: Denops, ...args: unknown[]): Promise { /** * Return the PID (process id) of `job-id` **{job}**. */ -export function jobpid(denops: Denops, job: unknown): Promise; +export function jobpid(denops: Denops, job: unknown): Promise; export function jobpid(denops: Denops, ...args: unknown[]): Promise { return denops.call("jobpid", ...args); } @@ -4883,7 +5035,7 @@ export function jobresize( job: unknown, width: unknown, height: unknown, -): Promise; +): Promise; export function jobresize( denops: Denops, ...args: unknown[] @@ -4892,17 +5044,19 @@ export function jobresize( } /** + * Note: Prefer `vim.system()` in Lua (unless using the `pty` option). + * * Spawns **{cmd}** as a job. * If **{cmd}** is a List it runs directly (no 'shell'). * If **{cmd}** is a String it runs in the 'shell', like this: * - * :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) + * call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) * * (See `shell-unquoting` for details.) * * Example: * - * :call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) + * call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) * * Returns `job-id` on success, 0 on invalid arguments (or job * table is full), -1 if **{cmd}**[0] or 'shell' is not executable. @@ -4917,11 +5071,11 @@ export function jobresize( * - cmd[0] must be an executable (not a "built-in"). If it is * in $PATH it can be called by name, without an extension: * - * :call jobstart(['ping', 'neovim.io']) + * call jobstart(['ping', 'neovim.io']) * * If it is a full or partial path, extension is required: * - * :call jobstart(['System32\ping.exe', 'neovim.io']) + * call jobstart(['System32\ping.exe', 'neovim.io']) * * - **{cmd}** is collapsed to a string of quoted args as expected * by CommandLineToArgvW https://msdn.microsoft.com/bb776391 @@ -4952,11 +5106,9 @@ export function jobresize( * stdout data. * `on_stderr`: (function) Callback invoked when the job emits * stderr data. - * overlapped: (boolean) Set FILE_FLAG_OVERLAPPED for the - * standard input/output passed to the child process. - * Normally you do not need to set this. - * (Only available on MS-Windows, On other - * platforms, this option is silently ignored.) + * overlapped: (boolean) Sets FILE_FLAG_OVERLAPPED for the + * stdio passed to the child process. Only on + * MS-Windows; ignored on other platforms. * pty: (boolean) Connect the job to a new pseudo * terminal, and its streams to the master file * descriptor. `on_stdout` receives all output, @@ -4986,7 +5138,7 @@ export function jobstart( denops: Denops, cmd: unknown, opts?: unknown, -): Promise; +): Promise; export function jobstart(denops: Denops, ...args: unknown[]): Promise { return denops.call("jobstart", ...args); } @@ -5001,7 +5153,7 @@ export function jobstart(denops: Denops, ...args: unknown[]): Promise { * Returns 1 for valid job id, 0 for invalid id, including jobs have * exited or stopped. */ -export function jobstop(denops: Denops, id: unknown): Promise; +export function jobstop(denops: Denops, id: unknown): Promise; export function jobstop(denops: Denops, ...args: unknown[]): Promise { return denops.call("jobstop", ...args); } @@ -5032,7 +5184,7 @@ export function jobwait( denops: Denops, jobs: unknown, timeout?: unknown, -): Promise; +): Promise; export function jobwait(denops: Denops, ...args: unknown[]): Promise { return denops.call("jobwait", ...args); } @@ -5044,8 +5196,8 @@ export function jobwait(denops: Denops, ...args: unknown[]): Promise { * **{path}** matches a menu by name, or all menus if **{path}** is an * empty string. Example: * - * :echo menu_get('File','') - * :echo menu_get('') + * echo menu_get('File','') + * echo menu_get('') * * **{modes}** is a string of zero or more modes (see `maparg()` or * `creating-menus` for the list of modes). "a" means "all". @@ -5088,13 +5240,13 @@ export function menu_get( denops: Denops, path: unknown, modes?: unknown, -): Promise; +): Promise; export function menu_get(denops: Denops, ...args: unknown[]): Promise { return denops.call("menu_get", ...args); } /** - * Convert a list of VimL objects to msgpack. Returned value is a + * Convert a list of Vimscript objects to msgpack. Returned value is a * `readfile()`-style list. When **{type}** contains "B", a `Blob` is * returned instead. Example: * @@ -5119,7 +5271,7 @@ export function msgpackdump( denops: Denops, list: unknown, type?: unknown, -): Promise; +): Promise; export function msgpackdump( denops: Denops, ...args: unknown[] @@ -5129,7 +5281,7 @@ export function msgpackdump( /** * Convert a `readfile()`-style list or a `Blob` to a list of - * VimL objects. + * Vimscript objects. * Example: * * let fname = expand('~/.config/nvim/shada/main.shada') @@ -5200,12 +5352,11 @@ export function msgpackdump( * 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. */ -export function msgpackparse(denops: Denops, data: unknown): Promise; +export function msgpackparse(denops: Denops, data: unknown): Promise; export function msgpackparse( denops: Denops, ...args: unknown[] @@ -5218,7 +5369,7 @@ export function msgpackparse( * Returns an empty string when nothing was recorded yet. * See `q` and `Q`. */ -export function reg_recorded(denops: Denops): Promise; +export function reg_recorded(denops: Denops): Promise; export function reg_recorded( denops: Denops, ...args: unknown[] @@ -5231,7 +5382,7 @@ export function reg_recorded( * If **{channel}** is 0, the event is broadcast to all channels. * Example: * - * :au VimLeave call rpcnotify(0, "leaving") + * au VimLeave call rpcnotify(0, "leaving") */ export function rpcnotify( denops: Denops, @@ -5251,7 +5402,7 @@ export function rpcnotify( * `RPC` and blocks until a response is received. * Example: * - * :let result = rpcrequest(rpc_chan, "func", 1, 2, 3) + * let result = rpcrequest(rpc_chan, "func", 1, 2, 3) */ export function rpcrequest( denops: Denops, @@ -5269,11 +5420,11 @@ export function rpcrequest( /** * Deprecated. Replace * - * :let id = rpcstart('prog', ['arg1', 'arg2']) + * let id = rpcstart('prog', ['arg1', 'arg2']) * * with * - * :let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) + * let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) */ export function rpcstart( denops: Denops, @@ -5303,20 +5454,21 @@ export function rpcstart(denops: Denops, ...args: unknown[]): Promise { * * - If **{address}** is omitted the name is "nvim". * - * :echo serverstart() + * echo serverstart() + * * => /tmp/nvim.bram/oknANW/nvim.15430.5 * * Example bash command to list all Nvim servers: * - * ls ${XDG_RUNTIME_DIR:-${TMPDIR}nvim.${USER}}/* /nvim.*.0 + * ls ${XDG_RUNTIME_DIR:-${TMPDIR}nvim.${USER}}/* /nvim.*.0 * * Example named pipe: * - * if has('win32') - * echo serverstart('\\.\pipe\nvim-pipe-1234') - * else - * echo serverstart('nvim.sock') - * endif + * if has('win32') + * echo serverstart('\\.\pipe\nvim-pipe-1234') + * else + * echo serverstart('nvim.sock') + * endif * * Example TCP/IP address: * @@ -5352,7 +5504,7 @@ export function serverstop( * **{address}** should be the path of a local domain socket (on * unix) or named pipe (on Windows). If **{mode}** is "tcp" then * **{address}** should be of the form "host:port" where the host - * should be an ip adderess or host name, and port the port + * should be an ip address or host name, and port the port * number. * * For "pipe" mode, see `luv-pipe-handle`. For "tcp" mode, see @@ -5377,7 +5529,7 @@ export function sockconnect( mode: unknown, address: unknown, opts?: unknown, -): Promise; +): Promise; export function sockconnect( denops: Denops, ...args: unknown[] @@ -5406,7 +5558,7 @@ export function sockconnect( * - `channel-id` on success (value is always 1) * - 0 on invalid arguments */ -export function stdioopen(denops: Denops, opts: unknown): Promise; +export function stdioopen(denops: Denops, opts: unknown): Promise; export function stdioopen( denops: Denops, ...args: unknown[] @@ -5434,12 +5586,9 @@ export function stdioopen( * * Example: * - * :echo stdpath("config") + * echo stdpath("config") */ -export function stdpath( - denops: Denops, - what: unknown, -): Promise; +export function stdpath(denops: Denops, what: unknown): Promise; export function stdpath(denops: Denops, ...args: unknown[]): Promise { return denops.call("stdpath", ...args); } @@ -5449,8 +5598,11 @@ export function stdpath(denops: Denops, ...args: unknown[]): Promise { * to the current (unmodified) buffer. Parameters and behavior * are the same as `jobstart()` except "pty", "width", "height", * and "TERM" are ignored: "height" and "width" are taken from - * the current window. - * Returns the same values as `jobstart()`. + * the current window. Note that termopen() implies a "pty" arg + * to jobstart(), and thus has the implications documented at + * `jobstart()`. + * + * Returns the same values as jobstart(). * * Terminal environment is initialized as in `jobstart-env`, * except $TERM is set to "xterm-256color". Full behavior is @@ -5486,7 +5638,7 @@ export function wait( timeout: unknown, condition: unknown, interval?: unknown, -): Promise; +): Promise; export function wait(denops: Denops, ...args: unknown[]): Promise { return denops.call("wait", ...args); } diff --git a/function/nvim/nvim_open_win.ts b/function/nvim/nvim_open_win.ts index 0e3fcf3a..a6518ed4 100644 --- a/function/nvim/nvim_open_win.ts +++ b/function/nvim/nvim_open_win.ts @@ -1,18 +1,28 @@ import type { Denops } from "../../mod.ts"; /** - * Open a new window. + * 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. * - * 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. + * 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 @@ -25,15 +35,22 @@ import type { Denops } from "../../mod.ts"; * 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 + * Example (Lua): window-relative float + * * vim.api.nvim_open_win(0, false, * {relative='win', row=3, col=3, width=12, height=3}) - * < * - * Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua + * Example (Lua): buffer-relative float (travels as buffer is scrolled) + * * vim.api.nvim_open_win(0, false, - * {relative='win', width=12, height=3, bufpos=**{100,10}**}) - * < + * {relative='win', width=12, height=3, bufpos={100,10}}) + * + * Example (Lua): vertical split left of the current window + * + * vim.api.nvim_open_win(0, false, { + * split = 'left', + * win = 0 + * }) * * Attributes: * not allowed when `textlock` is active @@ -49,25 +66,23 @@ import type { Denops } from "../../mod.ts"; * window. * - "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) * - "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: + * relative="win"). Takes a tuple of zero-indexed + * `[line, column]`. `row` and `col` if given are applied + * relative to this position, else they default to: * - `row=1` and `col=0` if `anchor` is "NW" or "NE" * - `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus * like a tooltip near the buffer text). - * * - row: Row position in units of "screen cell height", may be * fractional. * - col: Column position in units of "screen cell width", may @@ -78,8 +93,9 @@ import type { Denops } from "../../mod.ts"; * - 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 @@ -87,9 +103,8 @@ import type { Denops } from "../../mod.ts"; * 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: Configure the appearance of the window. Currently - * only takes one non-empty value: + * - style: (optional) Configure the appearance of the window. + * Currently only supports one value: * - "minimal" Nvim will display the window with many UI * options disabled. This is useful when displaying a * temporary float where the text should not be edited. @@ -100,42 +115,64 @@ import type { Denops } from "../../mod.ts"; * 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. * - If it is an array, it should have a length of eight or - * any divisor of eight. The array will specifify the eight + * 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 is [text, highlight] tuples. if is string the default - * highlight group is `FloatTitle`. - * - title_pos: Title position must set with title option. - * value can be of `left` `center` `right` default is left. - * - noautocmd: If true then no buffer-related autocommand - * events such as `BufEnter`, `BufLeave` or `BufWinEnter` may - * fire from calling this function. + * - title: Title (optional) in window border, string or list. + * List should consist of `[text, highlight]` tuples. If + * string, the default highlight group is `FloatTitle`. + * - title_pos: Title position. Must be set with `title` + * option. Value can be one of "left", "center", or "right". + * Default is `"left"`. + * - footer: Footer (optional) in window border, string or + * list. List should consist of `[text, highlight]` tuples. + * If string, the default highlight group is `FloatFooter`. + * - footer_pos: Footer position. Must be set with `footer` + * option. Value can be one of "left", "center", or "right". + * Default is `"left"`. + * - noautocmd: If true then all autocommands are blocked for + * the duration of the call. + * - fixed: If true when anchor is NW or SW, the float window + * would be kept fixed even if the window would be truncated. + * - hide: If true the floating window will be hidden. + * - vertical: Split vertically `:vertical`. + * - split: Split direction: "left", "right", "above", "below". * * Return: * Window handle, or 0 on error diff --git a/function/nvim/nvim_win_set_config.ts b/function/nvim/nvim_win_set_config.ts index ce6095e5..a10a8bf7 100644 --- a/function/nvim/nvim_win_set_config.ts +++ b/function/nvim/nvim_win_set_config.ts @@ -3,11 +3,11 @@ import type { Denops } from "@denops/core"; import type { NvimOpenWinConfig } from "./nvim_open_win.ts"; /** - * Configures window layout. Currently only for floating and external windows - * (including changing a split window to those layouts). + * Configures window layout. Cannot be used to move the last window in a + * tabpage to a different one. * - * When reconfiguring a floating window, absent option keys will not be - * changed. `row`/`col` and `relative` must be reconfigured together. + * When reconfiguring a window, absent option keys will not be changed. + * `row`/`col` and `relative` must be reconfigured together. * * Parameters: * - **{window}** Window handle, or 0 for current window diff --git a/function/vim/_generated.ts b/function/vim/_generated.ts index a1654991..90201f9d 100644 --- a/function/vim/_generated.ts +++ b/function/vim/_generated.ts @@ -450,57 +450,6 @@ export function exists_compiled( return denops.call("exists_compiled", ...args); } -/** - * **{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, 'used[v:val] = true') - * - * This records the items that are in the **{expr1}** list. - * - * Note that **{expr2}** is the result of expression and is then used - * as a command. Often it is good to use a `literal-string` to - * avoid having to double backslashes. - * - * If **{expr2}** is a `Funcref` it must take two arguments: - * 1. the key or the index of the current item. - * 2. the value of the current item. - * With a legacy script lambda you don't get an error if it only - * accepts one argument, but with a Vim9 lambda you get "E1106: - * One argument too many", the number of arguments must match. - * If the function returns a value, it is ignored. - * - * Returns **{expr1}** in all cases. - * When an error is encountered while executing **{expr2}** no - * further items in **{expr1}** are processed. - * When **{expr2}** is a Funcref errors inside a function are ignored, - * unless it was defined with the "abort" flag. - * - * Can also be used as a `method`: - * - * mylist->foreach(expr2) - */ -export function foreach( - denops: Denops, - expr1: unknown, - expr2: unknown, -): Promise | unknown | string>; -export function foreach(denops: Denops, ...args: unknown[]): Promise { - return denops.call("foreach", ...args); -} - /** * Move the Vim window to the foreground. Useful when sent from * a client to a Vim server. `remote_send()` @@ -545,73 +494,6 @@ export function getmouseshape( return denops.call("getmouseshape", ...args); } -/** - * 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. 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: - * - * type Specify the region's selection type - * (default: "v"): - * "v" for `characterwise` mode - * "V" for `linewise` mode - * `""` for `blockwise-visual` mode - * - * exclusive If `TRUE`, use exclusive 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 is useful to get text starting and ending in - * different columns, such as a `characterwise-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 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}** 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, which makes a - * difference if the buffer is displayed in a window with - * different 'virtualedit' or 'list' values. - * - * Examples: - * - * :xnoremap - * \ echow getregion( - * \ getpos('v'), getpos('.'), #{ type: mode() }) - * - * Can also be used as a `method`: - * - * getpos('.')->getregion(getpos("'a")) - */ -export function getregion( - denops: Denops, - pos1: unknown, - pos2: unknown, - opts?: unknown, -): Promise; -export function getregion( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("getregion", ...args); -} - /** * Same as `getregion()`, but returns a list of positions * describing the buffer text segments bound by **{pos1}** and @@ -625,10 +507,25 @@ export function getregion( * "bufnum" is the buffer number. * "lnum" and "col" are the position in the buffer. The first * column is 1. - * The "off" number is zero, unless 'virtualedit' is used. Then - * it is the offset in screen columns from the start of the - * character. E.g., a position within a `` or after the last - * character. + * If the "off" number of a starting position is non-zero, it is + * the offset in screen columns from the start of the character. + * E.g., a position within a `` or after the last character. + * If the "off" number of an ending position is non-zero, it is + * the offset of the character's first cell not included in the + * selection, otherwise all its cells are included. + * + * Apart from the options supported by `getregion()`, **{opts}** also + * supports the following: + * + * eol If `TRUE`, indicate positions beyond + * the end of a line with "col" values + * one more than the length of the line. + * If `FALSE`, positions are limited + * within their lines, and if a line is + * empty or the selection is entirely + * beyond the end of a line, a "col" + * value of 0 is used for both positions. + * (default: `FALSE`) * * Can also be used as a `method`: * @@ -1025,212 +922,6 @@ export function listener_remove( return denops.call("listener_remove", ...args); } -/** - * Evaluate Lua expression **{expr}** and return its result converted - * to Vim data structures. Second **{expr}** may hold additional - * argument accessible as _A inside first **{expr}**. - * Strings are returned as they are. - * Boolean objects are converted to numbers. - * Numbers are converted to `Float` values. - * Dictionaries and lists obtained by vim.eval() are returned - * as-is. - * Other objects are returned as zero without any errors. - * See `lua-luaeval` for more details. - * Note that in a `:def` function local variables are not visible - * to **{expr}**. - * - * Can also be used as a `method`: - * - * GetExpr()->luaeval() - * - * *only available when compiled with the `+lua` feature* - */ -export function luaeval( - denops: Denops, - expr1: unknown, - expr2?: unknown, -): Promise; -export function luaeval(denops: Denops, ...args: unknown[]): Promise { - return denops.call("luaeval", ...args); -} - -/** - * Returns a `List` of all mappings. Each List item is a `Dict`, - * the same as what is returned by `maparg()`, see - * `mapping-dict`. When **{abbr}** is there and it is `TRUE` use - * abbreviations instead of mappings. - * - * Example to show all mappings with 'MultiMatch' in rhs: - * - * vim9script - * echo maplist()->filter( - * (_, m) => match(m.rhs, 'MultiMatch') >= 0) - * - * It can be tricky to find mappings for particular `:map-modes`. - * `mapping-dict`'s "mode_bits" can simplify this. For example, - * the mode_bits for Normal, Insert or Command-line modes are - * 0x19. To find all the mappings available in those modes you - * can do: - * - * vim9script - * var saved_maps = [] - * for m in maplist() - * if and(m.mode_bits, 0x19) != 0 - * saved_maps->add(m) - * endif - * endfor - * echo saved_maps->mapnew((_, m) => m.lhs) - * - * The values of the mode_bits are defined in Vim's src/vim.h - * file and they can be discovered at runtime using - * `:map-commands` and "maplist()". Example: - * - * vim9script - * omap xyzzy - * var op_bit = maplist()->filter( - * (_, m) => m.lhs == 'xyzzy')[0].mode_bits - * ounmap xyzzy - * echo printf("Operator-pending mode bit: 0x%x", op_bit) - */ -export function maplist(denops: Denops, abbr?: unknown): Promise; -export function maplist(denops: Denops, ...args: unknown[]): Promise { - return denops.call("maplist", ...args); -} - -/** - * Like `map()` but instead of replacing items in **{expr1}** a new - * List or Dictionary is created and returned. **{expr1}** remains - * unchanged. Items can still be changed by **{expr2}**, if you - * don't want that use `deepcopy()` first. - */ -export function mapnew( - denops: Denops, - expr1: unknown, - expr2: unknown, -): Promise | unknown | string>; -export function mapnew(denops: Denops, ...args: unknown[]): Promise { - return denops.call("mapnew", ...args); -} - -/** - * 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. - * - * 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. - * - * Examples: - * - * " 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: - * - * " 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', '', '', '', '', '']}] - * - * The "submatches" List always contains 9 items. If a submatch - * is not found, then an empty string is returned for that - * submatch. - * - * Can also be used as a `method`: - * - * GetBuffer()->matchbufline('mypat', 1, '$') - */ -export function matchbufline( - denops: Denops, - buf: unknown, - pat: unknown, - lnum: unknown, - end: unknown, - dict?: unknown, -): Promise; -export function matchbufline( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("matchbufline", ...args); -} - -/** - * Returns the `List` of matches in **{list}** where **{pat}** matches. - * **{list}** is a `List` of strings. **{pat}** is matched against each - * string in **{list}**. - * - * 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. - * idx index in **{list}** of the match. - * text matched string - * 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: - * - * :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: - * - * :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', - * \ #{submatches: v:true}) - * [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] - * - * The "submatches" List always contains 9 items. If a submatch - * is not found, then an empty string is returned for that - * submatch. - * - * Can also be used as a `method`: - * - * GetListOfStrings()->matchstrlist('mypat') - */ -export function matchstrlist( - denops: Denops, - list: unknown, - pat: unknown, - dict?: unknown, -): Promise; -export function matchstrlist( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("matchstrlist", ...args); -} - /** * Evaluate MzScheme expression **{expr}** and return its result * converted to Vim data structures. @@ -1575,30 +1266,6 @@ export function server2client( return denops.call("server2client", ...args); } -/** - * Similar to using a `slice` "expr[start : end]", but "end" is - * used exclusive. And for a string the indexes are used as - * character indexes instead of byte indexes, like in - * `vim9script`. Also, composing characters are treated as a - * part of the preceding base character. - * When **{end}** is omitted the slice continues to the last item. - * When **{end}** is -1 the last item is omitted. - * Returns an empty value if **{start}** or **{end}** are invalid. - * - * Can also be used as a `method`: - * - * GetList()->slice(offset) - */ -export function slice( - denops: Denops, - expr: unknown, - start: unknown, - end?: unknown, -): Promise; -export function slice(denops: Denops, ...args: unknown[]): Promise { - return denops.call("slice", ...args); -} - /** * Stop playing all sounds. * @@ -1715,104 +1382,6 @@ export function sound_stop( return denops.call("sound_stop", ...args); } -/** - * Return a string which contains characters indicating the - * current state. Mostly useful in callbacks that want to do - * work that may not always be safe. Roughly this works like: - * - callback uses state() to check if work is safe to do. - * Yes: then do it right away. - * No: add to work queue and add a `SafeState` and/or - * `SafeStateAgain` autocommand (`SafeState` triggers at - * toplevel, `SafeStateAgain` triggers after handling - * messages and callbacks). - * - When SafeState or SafeStateAgain is triggered and executes - * your autocommand, check with `state()` if the work can be - * done now, and if yes remove it from the queue and execute. - * Remove the autocommand if the queue is now empty. - * Also see `mode()`. - * - * When **{what}** is given only characters in this string will be - * added. E.g, this checks if the screen has scrolled: - * - * if state('s') == '' - * " screen has not scrolled - * - * These characters indicate the state, generally indicating that - * something is busy: - * m halfway a mapping, :normal command, feedkeys() or - * stuffed command - * o operator pending, e.g. after `d` - * a Insert mode autocomplete active - * x executing an autocommand - * w blocked on waiting, e.g. ch_evalexpr(), ch_read() and - * ch_readraw() when reading json - * S not triggering SafeState or SafeStateAgain, e.g. after - * `f` or a count - * c callback invoked, including timer (repeats for - * recursiveness up to "ccc") - * s screen has scrolled for messages - */ -export function state(denops: Denops, what?: unknown): Promise; -export function state(denops: Denops, ...args: unknown[]): Promise { - return denops.call("state", ...args); -} - -/** - * The result is a Number, which is the number of UTF-16 code - * units in String **{string}** (after converting it to UTF-16). - * - * When **{countcc}** is TRUE, composing characters are counted - * separately. - * When **{countcc}** is omitted or FALSE, composing characters are - * ignored. - * - * Returns zero on error. - * - * Also see `strlen()` and `strcharlen()`. - * Examples: - * - * echo strutf16len('a') returns 1 - * echo strutf16len('©') returns 1 - * echo strutf16len('😊') returns 2 - * echo strutf16len('ą́') returns 1 - * echo strutf16len('ą́', v:true) returns 3 - * - * Can also be used as a `method`: - * - * GetText()->strutf16len() - */ -export function strutf16len( - denops: Denops, - string: unknown, - countcc?: unknown, -): Promise; -export function strutf16len( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("strutf16len", ...args); -} - -/** - * Returns a list of swap file names, like what "vim -r" shows. - * See the `-r` command argument. The 'directory' option is used - * for the directories to inspect. If you only want to get a - * list of swap files in the current directory then temporarily - * set 'directory' to a dot: - * - * let save_dir = &directory - * let &directory = '.' - * let swapfiles = swapfilelist() - * let &directory = save_dir - */ -export function swapfilelist(denops: Denops): Promise; -export function swapfilelist( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("swapfilelist", ...args); -} - /** * Returns a `Dictionary` with properties of the terminal that Vim * detected from the response to `t_RV` request. See @@ -1868,49 +1437,6 @@ export function typename(denops: Denops, ...args: unknown[]): Promise { return denops.call("typename", ...args); } -/** - * Same as `charidx()` but returns the UTF-16 code unit index of - * the byte at **{idx}** in **{string}** (after converting it to UTF-16). - * - * When **{charidx}** is present and TRUE, **{idx}** is used as the - * character index in the String **{string}** instead of as the byte - * index. - * An **{idx}** in the middle of a UTF-8 sequence is rounded - * downwards to the beginning of that sequence. - * - * Returns -1 if the arguments are invalid or if there are less - * than **{idx}** bytes in **{string}**. If there are exactly **{idx}** bytes - * the length of the string in UTF-16 code units is returned. - * - * See `byteidx()` and `byteidxcomp()` for getting the byte index - * from the UTF-16 index and `charidx()` for getting the - * character index from the UTF-16 index. - * Refer to `string-offset-encoding` for more information. - * Examples: - * - * echo utf16idx('a😊😊', 3) returns 2 - * echo utf16idx('a😊😊', 7) returns 4 - * echo utf16idx('a😊😊', 1, 0, 1) returns 2 - * echo utf16idx('a😊😊', 2, 0, 1) returns 4 - * echo utf16idx('aą́c', 6) returns 2 - * echo utf16idx('aą́c', 6, 1) returns 4 - * echo utf16idx('a😊😊', 9) returns -1 - * - * Can also be used as a `method`: - * - * GetName()->utf16idx(idx) - */ -export function utf16idx( - denops: Denops, - string: unknown, - idx: unknown, - countcc?: unknown, - charidx?: unknown, -): Promise; -export function utf16idx(denops: Denops, ...args: unknown[]): Promise { - return denops.call("utf16idx", ...args); -} - /** * Return non-zero when there is something to read from **{handle}**. * **{handle}** can be a Channel or a Job that has a Channel. @@ -3938,22 +3464,6 @@ export function test_feedinput( return denops.call("test_feedinput", ...args); } -/** - * Like garbagecollect(), but executed right away. This must - * only be called directly to avoid any structure to exist - * internally, and `v:testing` must have been set before calling - * any function. - * This will not work when called from a :def function, because - * variables on the stack will be freed. - */ -export function test_garbagecollect_now(denops: Denops): Promise; -export function test_garbagecollect_now( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("test_garbagecollect_now", ...args); -} - /** * Set the flag to call the garbagecollector as if in the main * loop. Only to be used in tests. @@ -4522,358 +4032,6 @@ export function test_void( return denops.call("test_void", ...args); } -/** - * Run **{cmd}** and add an error message to `v:errors` if it does - * NOT produce a beep or visual bell. - * Also see `assert_fails()`, `assert_nobeep()` and - * `assert-return`. - * - * Can also be used as a `method`: - * - * GetCmd()->assert_beeps() - */ -export function assert_beeps(denops: Denops, cmd: unknown): Promise; -export function assert_beeps( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_beeps", ...args); -} - -/** - * When **{expected}** and **{actual}** are not equal an error message is - * added to `v:errors` and 1 is returned. Otherwise zero is - * returned. `assert-return` - * The error is in the form "Expected **{expected}** but got - * **{actual}**". When **{msg}** is present it is prefixed to that. - * - * There is no automatic conversion, the String "4" is different - * from the Number 4. And the number 4 is different from the - * Float 4.0. The value of 'ignorecase' is not used here, case - * always matters. - * Example: - * - * assert_equal('foo', 'bar') - * - * Will result in a string to be added to `v:errors`: - * test.vim line 12: Expected 'foo' but got 'bar' - * - * Can also be used as a `method`, the base is passed as the - * second argument: - * - * mylist->assert_equal([1, 2, 3]) - */ -export function assert_equal( - denops: Denops, - expected: unknown, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_equal( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_equal", ...args); -} - -/** - * When the files **{fname-one}** and **{fname-two}** do not contain - * exactly the same text an error message is added to `v:errors`. - * Also see `assert-return`. - * When **{fname-one}** or **{fname-two}** does not exist the error will - * mention that. - * Mainly useful with `terminal-diff`. - * - * Can also be used as a `method`: - * - * GetLog()->assert_equalfile('expected.log') - */ -export function assert_equalfile( - denops: Denops, - fname_one: unknown, - fname_two: unknown, - msg?: unknown, -): Promise; -export function assert_equalfile( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_equalfile", ...args); -} - -/** - * When v:exception does not contain the string **{error}** an error - * message is added to `v:errors`. Also see `assert-return`. - * This can be used to assert that a command throws an exception. - * Using the error number, followed by a colon, avoids problems - * with translations: - * - * try - * commandthatfails - * call assert_false(1, 'command should have failed') - * catch - * call assert_exception('E492:') - * endtry - */ -export function assert_exception( - denops: Denops, - error: unknown, - msg?: unknown, -): Promise; -export function assert_exception( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_exception", ...args); -} - -/** - * Run **{cmd}** and add an error message to `v:errors` if it does - * NOT produce an error or when **{error}** is not found in the - * error message. Also see `assert-return`. - * - * When **{error}** is a string it must be found literally in the - * first reported error. Most often this will be the error code, - * including the colon, e.g. "E123:". - * - * assert_fails('bad cmd', 'E987:') - * - * When **{error}** is a `List` with one or two strings, these are - * used as patterns. The first pattern is matched against the - * first reported error: - * - * assert_fails('cmd', ['E987:.*expected bool']) - * - * The second pattern, if present, is matched against the last - * reported error. - * If there is only one error then both patterns must match. This - * can be used to check that there is only one error. - * To only match the last error use an empty string for the first - * error: - * - * assert_fails('cmd', ['', 'E987:']) - * - * If **{msg}** is empty then it is not used. Do this to get the - * default message when passing the **{lnum}** argument. - * - * When **{lnum}** is present and not negative, and the **{error}** - * argument is present and matches, then this is compared with - * the line number at which the error was reported. That can be - * the line number in a function or in a script. - * - * When **{context}** is present it is used as a pattern and matched - * against the context (script name or function name) where - * **{lnum}** is located in. - * - * Note that beeping is not considered an error, and some failing - * commands only beep. Use `assert_beeps()` for those. - * - * Can also be used as a `method`: - * - * GetCmd()->assert_fails('E99:') - */ -export function assert_fails( - denops: Denops, - cmd: unknown, - error?: unknown, - msg?: unknown, - lnum?: unknown, - context?: unknown, -): Promise; -export function assert_fails( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_fails", ...args); -} - -/** - * When **{actual}** is not false an error message is added to - * `v:errors`, like with `assert_equal()`. - * The error is in the form "Expected False but got **{actual}**". - * When **{msg}** is present it is prepended to that. - * Also see `assert-return`. - * - * A value is false when it is zero. When **{actual}** is not a - * number the assert fails. - * - * Can also be used as a `method`: - * - * GetResult()->assert_false() - */ -export function assert_false( - denops: Denops, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_false( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_false", ...args); -} - -/** - * This asserts number and `Float` values. When **{actual}** is lower - * than **{lower}** or higher than **{upper}** an error message is added - * to `v:errors`. Also see `assert-return`. - * The error is in the form "Expected range **{lower}** - **{upper}**, - * but got **{actual}**". When **{msg}** is present it is prefixed to - * that. - */ -export function assert_inrange( - denops: Denops, - lower: unknown, - upper: unknown, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_inrange( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_inrange", ...args); -} - -/** - * When **{pattern}** does not match **{actual}** an error message is - * added to `v:errors`. Also see `assert-return`. - * The error is in the form "Pattern **{pattern}** does not match - * **{actual}**". When **{msg}** is present it is prefixed to that. - * - * **{pattern}** is used as with `=~`: The matching is always done - * like 'magic' was set and 'cpoptions' is empty, no matter what - * the actual value of 'magic' or 'cpoptions' is. - * - * **{actual}** is used as a string, automatic conversion applies. - * Use "^" and "$" to match with the start and end of the text. - * Use both to match the whole text. - * - * Example: - * - * assert_match('^f.*o$', 'foobar') - * - * Will result in a string to be added to `v:errors`: - * test.vim line 12: Pattern '^f.*o$' does not match 'foobar' - * - * Can also be used as a `method`: - * - * getFile()->assert_match('foo.*') - */ -export function assert_match( - denops: Denops, - pattern: unknown, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_match( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_match", ...args); -} - -/** - * Run **{cmd}** and add an error message to `v:errors` if it - * produces a beep or visual bell. - * Also see `assert_beeps()`. - * - * Can also be used as a `method`: - * - * GetCmd()->assert_nobeep() - */ -export function assert_nobeep(denops: Denops, cmd: unknown): Promise; -export function assert_nobeep( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_nobeep", ...args); -} - -/** - * The opposite of `assert_equal()`: add an error message to - * `v:errors` when **{expected}** and **{actual}** are equal. - * Also see `assert-return`. - * - * Can also be used as a `method`: - * - * mylist->assert_notequal([1, 2, 3]) - */ -export function assert_notequal( - denops: Denops, - expected: unknown, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_notequal( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_notequal", ...args); -} - -/** - * The opposite of `assert_match()`: add an error message to - * `v:errors` when **{pattern}** matches **{actual}**. - * Also see `assert-return`. - * - * Can also be used as a `method`: - * - * getFile()->assert_notmatch('bar.*') - */ -export function assert_notmatch( - denops: Denops, - pattern: unknown, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_notmatch( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_notmatch", ...args); -} - -/** - * Report a test failure directly, using String **{msg}**. - * Always returns one. - * - * Can also be used as a `method`: - * - * GetMessage()->assert_report() - */ -export function assert_report(denops: Denops, msg: unknown): Promise; -export function assert_report( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_report", ...args); -} - -/** - * When **{actual}** is not true an error message is added to - * `v:errors`, like with `assert_equal()`. - * Also see `assert-return`. - * A value is TRUE when it is a non-zero number. When **{actual}** - * is not a number the assert fails. - * When **{msg}** is given it precedes the default message. - * - * Can also be used as a `method`: - * - * GetResult()->assert_true() - */ -export function assert_true( - denops: Denops, - actual: unknown, - msg?: unknown, -): Promise; -export function assert_true( - denops: Denops, - ...args: unknown[] -): Promise { - return denops.call("assert_true", ...args); -} - /** * Attach a text property at position **{lnum}**, **{col}**. **{col}** is * counted in bytes, use one for the first column. diff --git a/option/_generated.ts b/option/_generated.ts index f230ea34..58b9bdc6 100644 --- a/option/_generated.ts +++ b/option/_generated.ts @@ -2279,7 +2279,7 @@ export const comments: LocalOption = { /** * A template for a comment. The "%s" in the value is replaced with the * comment text. Currently only used to add markers for folding, see - * `fold-marker`. + * `fold-marker`. Also used by comment plugins `comment-install`. * * (default "/*%s* /") * @@ -12789,6 +12789,54 @@ export const smarttab: GlobalOption = { }, }; +/** + * Scrolling works with screen lines. When 'wrap' is set and the first + * line in the window wraps part of it may not be visible, as if it is + * above the window. `"<<<"` is displayed at the start of the first line, + * highlighted with `hl-NonText`. + * You may also want to add "lastline" to the 'display' option to show as + * much of the last line as possible. + * NOTE: partly implemented, doesn't work yet for `gj` and `gk`. + * + * (default off) + */ +export const smoothscroll: LocalOption = { + async get(denops: Denops): Promise { + const result = await options.get(denops, "smoothscroll"); + return Boolean(result ?? false); + }, + set(denops: Denops, value: boolean): Promise { + return options.set(denops, "smoothscroll", value); + }, + reset(denops: Denops): Promise { + return options.remove(denops, "smoothscroll"); + }, + async getLocal(denops: Denops): Promise { + const result = await localOptions.get(denops, "smoothscroll"); + return Boolean(result ?? false); + }, + setLocal(denops: Denops, value: boolean): Promise { + return localOptions.set(denops, "smoothscroll", value); + }, + resetLocal(denops: Denops): Promise { + return localOptions.remove(denops, "smoothscroll"); + }, + async getBuffer(denops: Denops, bufnr: number): Promise { + const result = await getbufvar(denops, bufnr, "&smoothscroll"); + return Boolean(result ?? false); + }, + setBuffer(denops: Denops, bufnr: number, value: boolean): Promise { + return setbufvar(denops, bufnr, "&smoothscroll", value); + }, + async getWindow(denops: Denops, winnr: number): Promise { + const result = await getwinvar(denops, winnr, "&smoothscroll"); + return Boolean(result ?? false); + }, + setWindow(denops: Denops, winnr: number, value: boolean): Promise { + return setwinvar(denops, winnr, "&smoothscroll", value); + }, +}; + /** * Number of spaces that a `` counts for while performing editing * operations, like inserting a `` or using ``. It "feels" like @@ -16292,6 +16340,52 @@ export const window: GlobalOption = { }, }; +/** + * If enabled, the window and the buffer it is displaying are paired. + * For example, attempting to change the buffer with `:edit` will fail. + * Other commands which change a window's buffer such as `:cnext` will + * also skip any window with 'winfixbuf' enabled. However if an Ex + * command has a "!" modifier, it can force switching buffers. + * + * (default off) + */ +export const winfixbuf: LocalOption = { + async get(denops: Denops): Promise { + const result = await options.get(denops, "winfixbuf"); + return Boolean(result ?? false); + }, + set(denops: Denops, value: boolean): Promise { + return options.set(denops, "winfixbuf", value); + }, + reset(denops: Denops): Promise { + return options.remove(denops, "winfixbuf"); + }, + async getLocal(denops: Denops): Promise { + const result = await localOptions.get(denops, "winfixbuf"); + return Boolean(result ?? false); + }, + setLocal(denops: Denops, value: boolean): Promise { + return localOptions.set(denops, "winfixbuf", value); + }, + resetLocal(denops: Denops): Promise { + return localOptions.remove(denops, "winfixbuf"); + }, + async getBuffer(denops: Denops, bufnr: number): Promise { + const result = await getbufvar(denops, bufnr, "&winfixbuf"); + return Boolean(result ?? false); + }, + setBuffer(denops: Denops, bufnr: number, value: boolean): Promise { + return setbufvar(denops, bufnr, "&winfixbuf", value); + }, + async getWindow(denops: Denops, winnr: number): Promise { + const result = await getwinvar(denops, winnr, "&winfixbuf"); + return Boolean(result ?? false); + }, + setWindow(denops: Denops, winnr: number, value: boolean): Promise { + return setwinvar(denops, winnr, "&winfixbuf", value); + }, +}; + /** * Keep the window height when windows are opened or closed and * 'equalalways' is set. Also for `CTRL-W_=`. Set by default for the diff --git a/option/nvim/_generated.ts b/option/nvim/_generated.ts index 5fec653d..b544a462 100644 --- a/option/nvim/_generated.ts +++ b/option/nvim/_generated.ts @@ -18,7 +18,7 @@ import type { * In a `:terminal` buffer this is the terminal channel. * Read-only. * - * (default: 0) + * (default 0) */ export const channel: LocalOption = { async get(denops: Denops): Promise { @@ -99,8 +99,9 @@ export const inccommand: GlobalOption = { /** * This option controls the number of lines / columns to scroll by when - * scrolling with a mouse. The option is a comma separated list of parts. - * Each part consists of a direction and a count as follows: + * scrolling with a mouse wheel (`scroll-mouse-wheel`). The option is + * a comma-separated list. Each part consists of a direction and a count + * as follows: * direction:count,direction:count * Direction is one of either "hor" or "ver". "hor" controls horizontal * scrolling and "ver" controls vertical scrolling. Count sets the amount @@ -112,7 +113,7 @@ export const inccommand: GlobalOption = { * * Example: * - * :set mousescroll=ver:5,hor:2 + * 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. @@ -151,8 +152,8 @@ export const mousescroll: GlobalOption = { * 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 + * set pumblend=15 + * hi PmenuSel blend=0 * * UI-dependent. Works best with RGB colors. 'termguicolors' * @@ -213,7 +214,7 @@ export const pumblend: GlobalOption = { * nodelta Send all internally redrawn cells to the UI, even if * they are unchanged from the already displayed state. * - * (default '') + * (default "") */ export const redrawdebug: GlobalOption = { async get(denops: Denops): Promise { @@ -244,7 +245,7 @@ export const redrawdebug: GlobalOption = { * Minimum is 1, maximum is 100000. * Only in `terminal` buffers. * - * (default: 10000) + * (default 10000) */ export const scrollback: LocalOption = { async get(denops: Denops): Promise { @@ -374,7 +375,7 @@ export const scrollback: LocalOption = { * * Example: * - * :set shada='50,<1000,s100,:0,n~/nvim/shada + * set shada='50,<1000,s100,:0,n~/nvim/shada * * '50 Marks will be remembered for the last 50 files you * edited. @@ -431,7 +432,7 @@ export const shada: GlobalOption = { * This option cannot be set from a `modeline` or in the `sandbox`, for * security reasons. * - * (default: "") + * (default "") */ export const shadafile: GlobalOption = { async get(denops: Denops): Promise { @@ -470,9 +471,13 @@ export const shadafile: GlobalOption = { * %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). + * 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. * * The `v:lnum` variable holds the line number to be drawn. * The `v:relnum` variable holds the relative line number to be drawn. @@ -480,35 +485,39 @@ export const shadafile: GlobalOption = { * 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 * handler should be written with this in mind. * - * Examples: >vim - * " Relative number with bar separator and click handlers: - * :set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T + * Examples: * - * " Right aligned relative cursor line number: - * :let &stc='%=%{v:relnum?v:relnum:v:lnum} ' + * " Relative number with bar separator and click handlers: + * set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T * - * " Line numbers in hexadecimal for non wrapped part of lines: - * :let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' + * " Right aligned relative cursor line number: + * let &stc='%=%{v:relnum?v:relnum:v:lnum} ' * - * " Human readable line numbers with thousands separator: - * :let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' - * . '%(\\d\\d\\d\\)\\+$",",","g")}' + * " Line numbers in hexadecimal for non wrapped part of lines: + * let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' * - * " Both relative and absolute line numbers with different - * " highlighting for odd and even relative numbers: - * :let &stc='%#NonText#%{&nu?v:lnum:""}' . - * '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' . - * '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}' + * " Human readable line numbers with thousands separator: + * let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' + * . '%(\\d\\d\\d\\)\\+$",",","g")}' * - * < WARNING: this expression is evaluated for each screen line so defining + * " Both relative and absolute line numbers with different + * " highlighting for odd and even relative numbers: + * let &stc='%#NonText#%{&nu?v:lnum:""}' . + * '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' . + * '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}' + * + * WARNING: this expression is evaluated for each screen line so defining * an expensive expression can negatively affect render performance. * - * (default: empty) + * (default "") */ export const statuscolumn: LocalOption = { async get(denops: Denops): Promise { @@ -567,7 +576,7 @@ export const statuscolumn: LocalOption = { * * C1 Control characters 0x80...0x9F * - * (default: "BS,HT,ESC,DEL") + * (default "BS,HT,ESC,DEL") */ export const termpastefilter: GlobalOption = { async get(denops: Denops): Promise { @@ -592,6 +601,37 @@ export const termpastefilter: GlobalOption = { }, }; +/** + * If the host terminal supports it, buffer all screen updates + * made during a redraw cycle so that each screen is displayed in + * the terminal all at once. This can prevent tearing or flickering + * when the terminal updates faster than Nvim can redraw. + * + * (default on) + */ +export const termsync: GlobalOption = { + async get(denops: Denops): Promise { + const result = await options.get(denops, "termsync"); + return Boolean(result ?? false); + }, + set(denops: Denops, value: boolean): Promise { + return options.set(denops, "termsync", value); + }, + reset(denops: Denops): Promise { + return options.remove(denops, "termsync"); + }, + async getGlobal(denops: Denops): Promise { + const result = await globalOptions.get(denops, "termsync"); + return Boolean(result ?? false); + }, + setGlobal(denops: Denops, value: boolean): Promise { + return globalOptions.set(denops, "termsync", value); + }, + resetGlobal(denops: Denops): Promise { + return globalOptions.remove(denops, "termsync"); + }, +}; + /** * When non-empty, this option enables the window bar and determines its * contents. The window bar is a bar that's shown at the top of every @@ -607,7 +647,7 @@ export const termpastefilter: GlobalOption = { * * This option cannot be set in a modeline when 'modelineexpr' is off. * - * (default empty) + * (default "") */ export const winbar: GlobalOrLocalOption = { async get(denops: Denops): Promise { @@ -721,7 +761,7 @@ export const winblend: LocalOption = { * * set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC * - * (default empty) + * (default "") */ export const winhighlight: LocalOption = { async get(denops: Denops): Promise { diff --git a/option/vim/_generated.ts b/option/vim/_generated.ts index 04a89a01..f2eb4e10 100644 --- a/option/vim/_generated.ts +++ b/option/vim/_generated.ts @@ -3096,54 +3096,6 @@ export const shortname: LocalOption = { }, }; -/** - * Scrolling works with screen lines. When 'wrap' is set and the first - * line in the window wraps part of it may not be visible, as if it is - * above the window. `"<<<"` is displayed at the start of the first line, - * highlighted with `hl-NonText`. - * You may also want to add "lastline" to the 'display' option to show as - * much of the last line as possible. - * NOTE: partly implemented, doesn't work yet for `gj` and `gk`. - * - * (default off) - */ -export const smoothscroll: LocalOption = { - async get(denops: Denops): Promise { - const result = await options.get(denops, "smoothscroll"); - return Boolean(result ?? false); - }, - set(denops: Denops, value: boolean): Promise { - return options.set(denops, "smoothscroll", value); - }, - reset(denops: Denops): Promise { - return options.remove(denops, "smoothscroll"); - }, - async getLocal(denops: Denops): Promise { - const result = await localOptions.get(denops, "smoothscroll"); - return Boolean(result ?? false); - }, - setLocal(denops: Denops, value: boolean): Promise { - return localOptions.set(denops, "smoothscroll", value); - }, - resetLocal(denops: Denops): Promise { - return localOptions.remove(denops, "smoothscroll"); - }, - async getBuffer(denops: Denops, bufnr: number): Promise { - const result = await getbufvar(denops, bufnr, "&smoothscroll"); - return Boolean(result ?? false); - }, - setBuffer(denops: Denops, bufnr: number, value: boolean): Promise { - return setbufvar(denops, bufnr, "&smoothscroll", value); - }, - async getWindow(denops: Denops, winnr: number): Promise { - const result = await getwinvar(denops, winnr, "&smoothscroll"); - return Boolean(result ?? false); - }, - setWindow(denops: Denops, winnr: number, value: boolean): Promise { - return setwinvar(denops, winnr, "&smoothscroll", value); - }, -}; - /** * When this option is not empty a swap file is synced to disk after * writing to it. This takes some time, especially on busy unix systems. @@ -4208,52 +4160,6 @@ export const wincolor: LocalOption = { }, }; -/** - * If enabled, the window and the buffer it is displaying are paired. - * For example, attempting to change the buffer with `:edit` will fail. - * Other commands which change a window's buffer such as `:cnext` will - * also skip any window with 'winfixbuf' enabled. However if an Ex - * command has a "!" modifier, it can force switching buffers. - * - * (default off) - */ -export const winfixbuf: LocalOption = { - async get(denops: Denops): Promise { - const result = await options.get(denops, "winfixbuf"); - return Boolean(result ?? false); - }, - set(denops: Denops, value: boolean): Promise { - return options.set(denops, "winfixbuf", value); - }, - reset(denops: Denops): Promise { - return options.remove(denops, "winfixbuf"); - }, - async getLocal(denops: Denops): Promise { - const result = await localOptions.get(denops, "winfixbuf"); - return Boolean(result ?? false); - }, - setLocal(denops: Denops, value: boolean): Promise { - return localOptions.set(denops, "winfixbuf", value); - }, - resetLocal(denops: Denops): Promise { - return localOptions.remove(denops, "winfixbuf"); - }, - async getBuffer(denops: Denops, bufnr: number): Promise { - const result = await getbufvar(denops, bufnr, "&winfixbuf"); - return Boolean(result ?? false); - }, - setBuffer(denops: Denops, bufnr: number, value: boolean): Promise { - return setbufvar(denops, bufnr, "&winfixbuf", value); - }, - async getWindow(denops: Denops, winnr: number): Promise { - const result = await getwinvar(denops, winnr, "&winfixbuf"); - return Boolean(result ?? false); - }, - setWindow(denops: Denops, winnr: number, value: boolean): Promise { - return setwinvar(denops, winnr, "&winfixbuf", value); - }, -}; - /** * Specifies the name of the winpty shared library, used for the * `:terminal` command. The default depends on whether Vim was built as a