diff --git a/denops_std/function/buffer.ts b/denops_std/function/buffer.ts index b9c4a838..04480bfc 100644 --- a/denops_std/function/buffer.ts +++ b/denops_std/function/buffer.ts @@ -1,12 +1,20 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; /** - * Add a buffer to the buffer list with {name}. + * Add a buffer to the buffer list with name {name} (must be a + * String). * If a buffer for file {name} already exists, return that buffer * number. Otherwise return the buffer number of the newly * created buffer. When {name} is an empty string then a new * buffer is always created. - * The buffer will not have' 'buflisted' set. + * The buffer will not have 'buflisted' set and not be loaded + * yet. To add some text to the buffer use this: + * let bufnr = bufadd('someName') + * call bufload(bufnr) + * call setbufline(bufnr, 1, ['some', 'text']) + * Returns 0 on error. + * Can also be used as a |method|: + * let bufnr = 'somename'->bufadd() */ export async function bufadd( denops: Denops, @@ -18,11 +26,11 @@ export async function bufadd( /** * The result is a Number, which is |TRUE| if a buffer called - * {expr} exists. - * If the {expr} argument is a number, buffer numbers are used. - * Number zero is the alternate buffer for the current window. + * {buf} exists. + * If the {buf} argument is a number, buffer numbers are used. * - * If the {expr} argument is a string it must match a buffer name + * Number zero is the alternate buffer for the current window. + * If the {buf} argument is a string it must match a buffer name * exactly. The name can be: * - Relative to the current directory. * - A full path. @@ -37,64 +45,80 @@ export async function bufadd( * for MS-Windows 8.3 names in the form "c:\DOCUME~1" * Use "bufexists(0)" to test for the existence of an alternate * file name. + * + * Can also be used as a |method|: + * let exists = 'somename'->bufexists() + * + * Obsolete name: buffer_exists(). */ export async function bufexists( denops: Denops, - expr: string | number, + buf: string | number, ): Promise { - const result = await denops.call("bufexists", expr) as number; + const result = await denops.call("bufexists", buf) as number; return !!result; } /** * The result is a Number, which is |TRUE| if a buffer called - * {expr} exists and is listed (has the 'buflisted' option set). - * The {expr} argument is used like with |bufexists()|. + * {buf} exists and is listed (has the 'buflisted' option set). + * The {buf} argument is used like with |bufexists()|. + * + * Can also be used as a |method|: + * let listed = 'somename'->buflisted() */ export async function buflisted( denops: Denops, - expr: string | number, + buf: string | number, ): Promise { - const result = await denops.call("buflisted", expr) as number; + const result = await denops.call("buflisted", buf) as number; return !!result; } /** - * Ensure the buffer {expr} is loaded. When the buffer name + * Ensure the buffer {buf} is loaded. When the buffer name * refers to an existing file then the file is read. Otherwise * the buffer will be empty. If the buffer was already loaded - * then there is no change. + * then there is no change. If the buffer is not related to a + * file the no file is read (e.g., when 'buftype' is "nofile"). * If there is an existing swap file for the file of the buffer, * there will be no dialog, the buffer will be loaded anyway. - * The {expr} argument is used like with |bufexists()|. + * The {buf} argument is used like with |bufexists()|. + * + * Can also be used as a |method|: + * eval 'somename'->bufload() */ export async function bufload( denops: Denops, - expr: string | number, + buf: string | number, ): Promise { - await denops.call("bufload", expr); + await denops.call("bufload", buf); } /** * The result is a Number, which is |TRUE| if a buffer called - * {expr} exists and is loaded (shown in a window or hidden). - * The {expr} argument is used like with |bufexists()|. + * {buf} exists and is loaded (shown in a window or hidden). + * The {buf} argument is used like with |bufexists()|. + * + * Can also be used as a |method|: + * let loaded = 'somename'->bufloaded() */ export async function bufloaded( denops: Denops, - expr: string | number, + buf: string | number, ): Promise { - const result = await denops.call("bufloaded", expr) as number; + const result = await denops.call("bufloaded", buf) as number; return !!result; } /** - * The result is the name of a buffer, as it is displayed by the - * ":ls" command. - * If {expr} is omitted the current buffer is used. - * If {expr} is a Number, that buffer number's name is given. + * The result is the name of a buffer. Mostly as it is displayed + * by the `:ls` command, but not using special names such as + * "[No Name]". + * If {buf} is omitted the current buffer is used. + * If {buf} is a Number, that buffer number's name is given. * Number zero is the alternate buffer for the current window. - * If {expr} is a String, it is used as a |file-pattern| to match + * If {buf} is a String, it is used as a |file-pattern| to match * with the buffer names. This is always done like 'magic' is * set and 'cpoptions' is empty. When there is more than one * match an empty string is returned. @@ -107,87 +131,106 @@ export async function bufloaded( * Listed buffers are found first. If there is a single match * with a listed buffer, that one is returned. Next unlisted * buffers are searched for. - * If the {expr} is a String, but you want to use it as a buffer - * number, force it to be a Number by adding zero to it: > - * :echo bufname("3" + 0) + * If the {buf} is a String, but you want to use it as a buffer + * number, force it to be a Number by adding zero to it: + * :echo bufname("3" + 0) + * Can also be used as a |method|: + * echo bufnr->bufname() + * * If the buffer doesn't exist, or doesn't have a name, an empty * string is returned. - * bufname("#") alternate buffer name - * bufname(3) name of buffer 3 - * bufname("%") name of current buffer - * bufname("file2") name of buffer where "file2" matches. + * bufname("#") alternate buffer name + * bufname(3) name of buffer 3 + * bufname("%") name of current buffer + * bufname("file2") name of buffer where "file2" matches. + * + * Obsolete name: buffer_name(). */ export async function bufname( denops: Denops, - expr?: string | number, + buf?: string | number, ): Promise { - return await denops.call("bufname", expr) as string; + return await denops.call("bufname", buf) as string; } /** * The result is the number of a buffer, as it is displayed by - * the ":ls" command. For the use of {expr}, see |bufname()| + * the `:ls` command. For the use of {buf}, see |bufname()| * above. * If the buffer doesn't exist, -1 is returned. Or, if the - * {create} argument is present and not zero, a new, unlisted, - * buffer is created and its number is returned. + * {create} argument is present and TRUE, a new, unlisted, + * buffer is created and its number is returned. Example: + * let newbuf = bufnr('Scratch001', 1) + * Using an empty name uses the current buffer. To create a new + * buffer with an empty name use |bufadd()|. * bufnr("$") is the last buffer: * :let last_buffer = bufnr("$") * The result is a Number, which is the highest buffer number * of existing buffers. Note that not all buffers with a smaller * number necessarily exist, because ":bwipeout" may have removed * them. Use bufexists() to test for the existence of a buffer. + * + * Can also be used as a |method|: + * echo bufref->bufnr() + * + * Obsolete name: buffer_number(). + * Obsolete name for bufnr("$"): last_buffer_nr(). */ export async function bufnr( denops: Denops, - expr?: string | number, + buf?: string | number, create?: boolean, ): Promise { - return await denops.call("bufnr", expr, create) as number; + return await denops.call("bufnr", buf, create) as number; } /** * The result is a Number, which is the |window-ID| of the first - * window associated with buffer {expr}. For the use of {expr}, - * see |bufname()| above. If buffer {expr} doesn't exist or - * there is no such window, -1 is returned. Example: > + * window associated with buffer {buf}. For the use of {buf}, + * see |bufname()| above. If buffer {buf} doesn't exist or + * there is no such window, -1 is returned. Example: * - * echo "A window containing buffer 1 is " . (bufwinid(1)) + * echo "A window containing buffer 1 is " .. (bufwinid(1)) * * Only deals with the current tab page. + * + * Can also be used as a |method|: + * FindBuffer()->bufwinid() */ export async function bufwinid( denops: Denops, - expr: string | number, + buf: string | number, ): Promise { - return await denops.call("bufwinid", expr) as number; + return await denops.call("bufwinid", buf) as number; } /** - * The result is a Number, which is the number of the first - * window associated with buffer {expr}. For the use of {expr}, - * see |bufname()| above. If buffer {expr} doesn't exist or - * there is no such window, -1 is returned. Example: > + * Like |bufwinid()| but return the window number instead of the + * |window-ID|. + * If buffer {buf} doesn't exist or there is no such window, -1 + * is returned. Example: * - * echo "A window containing buffer 1 is " . (bufwinnr(1)) + * echo "A window containing buffer 1 is " .. (bufwinnr(1)) * * The number can be used with |CTRL-W_w| and ":wincmd w" * |:wincmd|. - * Only deals with the current tab page. + * + * Can also be used as a |method|: + * FindBuffer()->bufwinnr() */ export async function bufwinnr( denops: Denops, - expr: string | number, + buf: string | number, ): Promise { - return await denops.call("bufwinnr", expr) as number; + return await denops.call("bufwinnr", buf) as number; } /** * Return a |List| with the lines starting from {lnum} to {end} - * (inclusive) in the buffer {expr}. If {end} is omitted, a + * (inclusive) in the buffer {buf}. If {end} is omitted, a * |List| with only the line {lnum} is returned. * - * For the use of {expr}, see |bufname()| above. + * For the use of {buf}, see |bufname()| above. * * For {lnum} and {end} "$" can be used for the last line of the * buffer. Otherwise a number must be used. @@ -203,37 +246,56 @@ export async function bufwinnr( * This function works only for loaded buffers. For unloaded and * non-existing buffers, an empty |List| is returned. * - * Example: > + * Example: * :let lines = getbufline(bufnr("myfile"), 1, "$") + * + * Can also be used as a |method|: + * GetBufnr()->getbufline(lnum) */ export async function getbufline( denops: Denops, - expr: string | number, + buf: string | number, lnum: string | number, end?: string | number, ): Promise { - return await denops.call("getbufline", expr, lnum, end) as string[]; + return await denops.call("getbufline", buf, lnum, end) as string[]; } /** - * Set line {lnum} to {text} in buffer {expr}. To insert - * lines use |append()|. + * Set line {lnum} to {text} in buffer {buf}. This works like + * |setline()| for the specified buffer. + * + * This function works only for loaded buffers. First call + * |bufload()| if needed. * - * For the use of {expr}, see |bufname()| above. + * To insert lines use |appendbufline()|. + * Any text properties in {lnum} are cleared. + * {text} can be a string to set one line, or a list of strings + * to set multiple lines. If the list extends below the last + * line then those lines are added. + * + * For the use of {buf}, see |bufname()| above. * * {lnum} is used like with |setline()|. - * This works like |setline()| for the specified buffer. - * On success 0 is returned, on failure 1 is returned. + * Use "$" to refer to the last line in buffer {buf}. + * When {lnum} is just below the last line the {text} will be + * added below the last line. + * + * When {buf} is not a valid buffer, the buffer is not loaded or + * {lnum} is not valid then 1 is returned. In |Vim9| script an + * error is given. + * On success 0 is returned. * - * If {expr} is not a valid buffer or {lnum} is not valid, an - * error message is given. + * Can also be used as a |method|, the base is passed as the + * third argument: + * GetText()->setbufline(buf, lnum) */ export async function setbufline( denops: Denops, - expr: string | number, + buf: string | number, lnum: string | number, text: string | string[], ): Promise { - const result = await denops.call("setbufline", expr, lnum, text) as number; + const result = await denops.call("setbufline", buf, lnum, text) as number; return !!result; } diff --git a/denops_std/function/common.ts b/denops_std/function/common.ts index 40564b06..04b9dffc 100644 --- a/denops_std/function/common.ts +++ b/denops_std/function/common.ts @@ -1,29 +1,29 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; /** - * The result is a Number, which is |TRUE| if {expr} is - * defined, zero otherwise. + * The result is a Number, which is |TRUE| if {expr} is defined, + * zero otherwise. + * + * Note: In a compiled |:def| function the evaluation is done at + * runtime. Use `exists_compiled()` to evaluate the expression + * at compile time. * * For checking for a supported feature use |has()|. * For checking if a file exists use |filereadable()|. * * The {expr} argument is a string, which contains one of these: - * &option-name Vim option (only checks if it exists, - * not if it really works) - * +option-name Vim option that works. - * $ENVNAME environment variable (could also be - * done by comparing with an empty - * string) - * *funcname built-in function (see |functions|) - * or user defined function (see - * |user-functions|). Also works for a - * variable that is a Funcref. * varname internal variable (see - * |internal-variables|). Also works - * for |curly-braces-names|, |Dictionary| - * entries, |List| items, etc. Beware - * that evaluating an index may cause an - * error message for an invalid + * dict.key |internal-variables|). Also works + * list[i] for |curly-braces-names|, |Dictionary| + * import.Func entries, |List| items, imported + * items, etc. + * Does not work for local variables in a + * compiled `:def` function. + * Also works for a function in |Vim9| + * script, since it can be used as a + * function reference. + * Beware that evaluating an index may + * cause an error message for an invalid * expression. E.g.: * :let l = [1, 2, 3] * :echo exists("l[5]") @@ -31,6 +31,20 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * :echo exists("l[xx]") * E121: Undefined variable: xx * 0 + * &option-name Vim option (only checks if it exists, + * not if it really works) + * +option-name Vim option that works. + * $ENVNAME environment variable (could also be + * done by comparing with an empty + * string) + * *funcname built-in function (see |functions|) + * or user defined function (see + * |user-functions|) that is implemented. + * Also works for a variable that is a + * Funcref. + * ?funcname built-in function that could be + * implemented; to be used to check if + * "funcname" is valid * :cmdname Ex command: built-in command, user * command or command modifier |:command|. * Returns: @@ -40,7 +54,9 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * To check for a supported command * always check the return value to be 2. * :2match The |:2match| command. - * :3match The |:3match| command. + * :3match The |:3match| command (but you + * probably should not use it, it is + * reserved for internal usage) * #event autocommand defined for this event * #event#pattern autocommand defined for this event and * pattern (the pattern is taken @@ -57,10 +73,11 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * supported. * * Examples: - * exists("&mouse") + * exists("&shortname") * exists("$HOSTNAME") * exists("*strftime") - * exists("*s:MyFunc") + * exists("*s:MyFunc") " only for legacy script + * exists("*MyFunc") * exists("bufcount") * exists(":Make") * exists("#CursorHold") @@ -72,18 +89,21 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * There must be no space between the symbol (&/$/* /#) and the * name. * There must be no extra characters after the name, although in - * a few cases this is ignored. That may become more strict in - * the future, thus don't count on it! + * a few cases this is ignored. That may become stricter in the + * future, thus don't count on it! * Working example: * exists(":make") * NOT working example: * exists(":make install") - + * * Note that the argument must be a string, not the name of the * variable itself. For example: * exists(bufcount) * This doesn't check for existence of the "bufcount" variable, * but gets the value of "bufcount", and checks if that exists. + * + * Can also be used as a |method|: + * Varname()->exists() */ export async function exists( denops: Denops, @@ -98,6 +118,16 @@ export async function exists( * {feature} argument is a feature name like "nvim-0.2.1" or * "win32", see below. See also |exists()|. * + * If the code has a syntax error, then Nvim may skip the rest + * of the line and miss |:endif|. + * if has('feature') | let x = this->breaks->without->the->feature | endif + * + * Put |:if| and |:endif| on separate lines to avoid the + * syntax error. + * if has('feature') + * let x = this->breaks->without->the->feature + * endif + * * Vim's compile-time feature-names (prefixed with "+") are not * recognized because Nvim is always compiled with all possible * features. |feature-compile| @@ -110,24 +140,29 @@ export async function exists( * 2. Runtime condition or other pseudo-feature. For example the * "win32" feature checks if the current system is Windows: * :if has("win32") - * *feature-list* + * *feature-list* * List of supported pseudo-feature names: - * acl |ACL| support - * iconv Can use |iconv()| for conversion. - * +shellslash Can use backslashes in filenames (Windows) + * acl |ACL| support. + * bsd BSD system (not macOS, use "mac" for that). * clipboard |clipboard| provider is available. + * fname_case Case in file names matters (for Darwin and MS-Windows + * this is not present). + * iconv Can use |iconv()| for conversion. + * linux Linux system. + * mac MacOS system. * nvim This is Nvim. - * python2 Legacy Vim |python2| interface. |has-python| * python3 Legacy Vim |python3| interface. |has-python| * pythonx Legacy Vim |python_x| interface. |has-pythonx| - * ttyin input is a terminal (tty) - * ttyout output is a terminal (tty) + * sun SunOS system. + * ttyin input is a terminal (tty). + * ttyout output is a terminal (tty). * unix Unix system. * *vim_starting* True during |startup|. * win32 Windows system (32 or 64 bit). - * wsl WSL (Windows Subsystem for Linux) system + * win64 Windows system (64 bit). + * wsl WSL (Windows Subsystem for Linux) system. * - * *has-patch* + * *has-patch* * 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") @@ -147,14 +182,14 @@ export async function has( /** * Without {end} the result is a String, which is line {lnum} - * from the current buffer. Example: > + * from the current buffer. Example: * getline(1) * When {lnum} is a String that doesn't start with a - * digit, line() is called to translate the String into a Number. - * To get the line under the cursor: > + * digit, |line()| is called to translate the String into a Number. + * To get the line under the cursor: * getline(".") - * When {lnum} is smaller than 1 or bigger than the number of - * lines in the buffer, an empty string is returned. + * When {lnum} is a number smaller than 1 or bigger than the + * number of lines in the buffer, an empty string is returned. * * When {end} is given the result is a |List| where each item is * a line from the current buffer in the range {lnum} to {end}, @@ -162,11 +197,14 @@ export async function has( * {end} is used in the same way as {lnum}. * Non-existing lines are silently omitted. * When {end} is before {lnum} an empty |List| is returned. - * Example: > + * Example: * :let start = line('.') * :let end = search("^$") - 1 * :let lines = getline(start, end) * + * Can also be used as a |method|: + * ComputeLnum()->getline() + * * To get lines from another buffer see |getbufline()| */ export async function getline( @@ -189,14 +227,17 @@ export async function getline( /** * Set line {lnum} of the current buffer to {text}. To insert * lines use |append()|. To set lines in another buffer use - * |setbufline()|. + * |setbufline()|. Any text properties in {lnum} are cleared. * * {lnum} is used like with |getline()|. * When {lnum} is just below the last line the {text} will be - * added as a new line. + * added below the last line. + * {text} can be any type or a List of any type, each item is + * converted to a String. * - * If this succeeds, 0 is returned. If this fails (most likely - * because {lnum} is invalid) 1 is returned. + * If this succeeds, FALSE is returned. If this fails (most likely + * because {lnum} is invalid) TRUE is returned. + * In |Vim9| script an error is given if {lnum} is invalid. * * Example: * :call setline(5, strftime("%c")) @@ -210,6 +251,10 @@ export async function getline( * :endfor * * Note: The '[ and '] marks are not set. + * + * Can also be used as a |method|, the base is passed as the + * second argument: + * GetText()->setline(lnum) */ export async function setline( denops: Denops, diff --git a/denops_std/function/cursor.ts b/denops_std/function/cursor.ts index 214c4c08..c48e3b3c 100644 --- a/denops_std/function/cursor.ts +++ b/denops_std/function/cursor.ts @@ -19,23 +19,24 @@ import type { Position, ScreenPos } from "./types.ts"; * out of range then col() returns zero. * To get the line number use |line()|. To get both use * |getpos()|. - * For the screen column position use |virtcol()|. + * For the screen column position use |virtcol()|. For the + * character position use |charcol()|. * Note that only marks in the current file can be used. * Examples: * col(".") column of cursor * col("$") length of cursor line plus one * col("'t") column of mark t - * col("'" . markname) column of mark markname - * The first column is 1. 0 is returned for an error. + * col("'" .. markname) column of mark markname + * The first column is 1. Returns 0 if {expr} is invalid. * For an uppercase mark the column may actually be in another * buffer. * For the cursor position, when 'virtualedit' is active, the * column is one higher if the cursor is after the end of the * line. This can be used to obtain the column in Insert mode: - * :imap :let save_ve = &ve:set ve=all:echo col(".") . "\n" :let save_ve = &ve + * \:set ve=all + * \:echo col(".") .. "\n" + * \let &ve = save_ve * GetPos()->col() */ export async function col( @@ -57,12 +58,13 @@ export async function col( * set to 8, it returns 8. |conceal| is ignored. * For the byte position use |col()|. * For the use of {expr} see |col()|. - * When 'virtualedit' is used {expr} can be [lnum, col, off], where - * "off" is the offset in screen columns from the start of the - * character. E.g., a position within a or after the last - * character. When "off" is omitted zero is used. - * When Virtual editing is active in the current mode, a position - * beyond the end of the line can be returned. |'virtualedit'| + * When 'virtualedit' is used {expr} can be [lnum, col, off], + * where "off" is the offset in screen columns from the start of + * the character. E.g., a position within a or after the + * last character. When "off" is omitted zero is used. When + * Virtual editing is active in the current mode, a position + * beyond the end of the line can be returned. Also see + * |'virtualedit'| * The accepted positions are: * . the cursor position * $ the end of the cursor line (the result is the @@ -101,7 +103,8 @@ export async function virtcol( /** * The result is a Number, which is the line number of the file - * position given with {expr}. The accepted positions are: + * position given with {expr}. The {expr} argument is a string. + * The accepted positions are: * . the cursor position * $ the last line in the current buffer * 'x position of mark x (if the mark is not set, 0 is @@ -118,17 +121,27 @@ export async function virtcol( * then applies to another buffer. * To get the column number use |col()|. To get both use * |getpos()|. + * With the optional {winid} argument the values are obtained for + * that window instead of the current window. + * Returns 0 for invalid values of {expr} and {winid}. * Examples: * line(".") line number of the cursor + * line(".", winid) idem, in window "winid" * line("'t") line number of mark t - * line("'" . marker) line number of mark marker + * line("'" .. marker) line number of mark marker + * * To jump to the last known position when opening a file see * |last-position-jump|. + * * Can also be used as a |method|: * GetValue()->line() */ -export async function line(denops: Denops, expr: string): Promise { - return await denops.call("line", expr) as number; +export async function line( + denops: Denops, + expr: string, + winid?: number | string, +): Promise { + return await denops.call("line", expr, winid) as number; } /** @@ -154,6 +167,7 @@ export async function winline(denops: Denops): Promise { /** * Positions the cursor at the column (byte count) {col} in the * line {lnum}. The first column is one. + * * When there is one argument {list} this is used as a |List| * with two, three or four item: * [{lnum}, {col}] @@ -161,7 +175,12 @@ export async function winline(denops: Denops): Promise { * [{lnum}, {col}, {off}, {curswant}] * This is like the return value of |getpos()| or |getcurpos()|, * but without the first item. + * + * To position the cursor using the character count, use + * |setcursorcharpos()|. + * * Does not change the jumplist. + * {lnum} is used like with |getline()|. * If {lnum} is greater than the number of lines in the buffer, * the cursor will be positioned at the last line in the buffer. * If {lnum} is zero, the cursor will stay in the current line. @@ -171,10 +190,12 @@ export async function winline(denops: Denops): Promise { * If {col} is zero, the cursor will stay in the current column. * If {curswant} is given it is used to set the preferred column * for vertical movement. Otherwise {col} is used. + * * When 'virtualedit' is used {off} specifies the offset in * screen columns from the start of the character. E.g., a * position within a or after the last character. * Returns 0 when the position could be set, -1 otherwise. + * * Can also be used as a |method|: * GetCursorPos()->cursor() */ @@ -218,6 +239,14 @@ export async function cursor( * The "curscol" value is where the cursor would be placed. For * a Tab it would be the same as "endcol", while for a double * width character it would be the same as "col". + * The |conceal| feature is ignored here, the column numbers are + * as if 'conceallevel' is zero. You can set the cursor to the + * right position and use |screencol()| to get the value with + * |conceal| taken into account. + * If the position is in a closed fold the screen position of the + * first character is returned, {col} is not used. + * Returns an empty Dict if {winid} is invalid. + * * Can also be used as a |method|: * GetWinid()->screenpos(lnum, col) */ @@ -232,26 +261,42 @@ export async function screenpos( /** * Get the position of the cursor. This is like getpos('.'), but - * includes an extra item in the list: - * [bufnum, lnum, col, off, curswant] ~ + * includes an extra "curswant" item in the list: + * [0, lnum, col, off, curswant] ~ * The "curswant" number is the preferred column when moving the - * cursor vertically. Also see |getpos()|. + * cursor vertically. After |$| command it will be a very large + * number equal to |v:maxcol|. Also see |getcursorcharpos()| and + * |getpos()|. + * The first "bufnum" item is always zero. The byte position of + * the cursor is returned in 'col'. To get the character + * position, use |getcursorcharpos()|. + * + * The optional {winid} argument can specify the window. It can + * be the window number or the |window-ID|. The last known + * cursor position is returned, this may be invalid for the + * current value of the buffer if it is not the current window. + * If {winid} is invalid a list with zeroes is returned. + * * This can be used to save and restore the cursor position: * let save_cursor = getcurpos() * MoveTheCursorAround * call setpos('.', save_cursor) * Note that this only works within the window. See * |winrestview()| for restoring more state. + * + * Can also be used as a |method|: + * GetWinid()->getcurpos() */ export async function getcurpos( denops: Denops, + winid?: number | string, ): Promise { - return await denops.call("getcurpos") as Position; + return await denops.call("getcurpos", winid) as Position; } /** - * Get the position for {expr}. For possible values of {expr} - * see |line()|. For getting the cursor position see + * Get the position for String {expr}. For possible values of + * {expr} see |line()|. For getting the cursor position see * |getcurpos()|. * The result is a |List| with four numbers: * [bufnum, lnum, col, off] @@ -265,12 +310,19 @@ export async function getcurpos( * character. * Note that for '< and '> Visual mode matters: when it is "V" * (visual line mode) the column of '< is zero and the column of - * '> is a large number. + * '> is a large number equal to |v:maxcol|. + * The column number in the returned List is the byte position + * within the line. To get the character position in the line, + * use |getcharpos()|. + * A very large column number equal to |v:maxcol| can be returned, + * in which case it means "after the end of the line". + * If {expr} is invalid, returns a list with all zeros. * This can be used to save and restore the position of a mark: * let save_a_mark = getpos("'a") * ... * call setpos("'a", save_a_mark) - * Also see |getcurpos()| and |setpos()|. + * Also see |getcharpos()|, |getcurpos()| and |setpos()|. + * * Can also be used as a |method|: * GetMark()->getpos() */ @@ -279,12 +331,13 @@ export async function getpos(denops: Denops, expr: string): Promise { } /** - * Set the position for {expr}. Possible values: + * Set the position for String {expr}. Possible values: * . the cursor * 'x mark x * {list} must be a |List| with four or five numbers: * [bufnum, lnum, col, off] * [bufnum, lnum, col, off, curswant] + * * "bufnum" is the buffer number. Zero can be used for the * current buffer. When setting an uppercase mark "bufnum" is * used for the mark position. For other marks it specifies the @@ -293,29 +346,38 @@ export async function getpos(denops: Denops, expr: string): Promise { * For setting the cursor and the ' mark "bufnum" is ignored, * since these are associated with a window, not a buffer. * Does not change the jumplist. + * * "lnum" and "col" are the position in the buffer. The first * column is 1. Use a zero "lnum" to delete a mark. If "col" is - * smaller than 1 then 1 is used. + * smaller than 1 then 1 is used. To use the character count + * instead of the byte count, use |setcharpos()|. + * * The "off" number is only used when 'virtualedit' is set. 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. + * * The "curswant" number is only used when setting the cursor * position. It sets the preferred column for when moving the * cursor vertically. When the "curswant" number is missing the * preferred column is not set. When it is present and setting a * mark position it is not used. + * * Note that for '< and '> changing the line number may result in * the marks to be effectively be swapped, so that '< is always * before '>. + * * Returns 0 when the position could be set, -1 otherwise. * An error message is given if {expr} is invalid. - * Also see |getpos()| and |getcurpos()|. + * + * Also see |setcharpos()|, |getpos()| and |getcurpos()|. + * * This does not restore the preferred column for moving * vertically; if you set the cursor position with this, |j| and * |k| motions will jump to previous columns! Use |cursor()| to * also set the preferred column. Also see the "curswant" key in * |winrestview()|. + * * Can also be used as a |method|: * GetPosition()->setpos('.') */ @@ -334,6 +396,9 @@ export async function setpos( * for the current buffer. The first character has byte count * one. * Also see |line2byte()|, |go| and |:goto|. + * + * Returns -1 if the {byte} value is invalid. + * * Can also be used as a |method|: * GetOffset()->byte2line() * {not available when compiled without the |+byte_offset| @@ -352,10 +417,11 @@ export async function byte2line(denops: Denops, byte: number): Promise { * below the last line: * line2byte(line("$") + 1) * This is the buffer size plus one. If 'fileencoding' is empty - * it is the file size plus one. - * When {lnum} is invalid, or the |+byte_offset| feature has been - * disabled at compile time, -1 is returned. + * it is the file size plus one. {lnum} is used like with + * |getline()|. When {lnum} is invalid, or the |+byte_offset| + * feature has been disabled at compile time, -1 is returned. * Also see |byte2line()|, |go| and |:goto|. + * * Can also be used as a |method|: * GetLnum()->line2byte() */ @@ -371,6 +437,7 @@ export async function line2byte(denops: Denops, lnum: number): Promise { * {lnum} is used like with |getline()|. Thus "." is the current * line, "'m" mark m, etc. * Returns 0 if the current window is not in diff mode. + * * Can also be used as a |method|: * GetLnum()->diff_filler() */ diff --git a/denops_std/function/cursor_test.ts b/denops_std/function/cursor_test.ts index 512ee74a..22846115 100644 --- a/denops_std/function/cursor_test.ts +++ b/denops_std/function/cursor_test.ts @@ -42,10 +42,14 @@ test({ name: "line()", fn: async () => { await denops.cmd("enew!"); + const winid = await denops.call("bufwinid", "%") as number; await denops.call("setline", 1, ["a", "b", "c"]); + assertNumber(await cursor.line(denops, ".")); assertEquals(await cursor.line(denops, "."), 1); assertEquals(await cursor.line(denops, "$"), 3); + assertNumber(await cursor.line(denops, ".", winid)); + assertEquals(await cursor.line(denops, ".", winid), 1); }, }); @@ -80,6 +84,9 @@ test({ name: "screenpos()", fn: async () => { await denops.cmd("enew!"); + const winid = await denops.call("bufwinid", "%") as number; + + assertScreenPos(await cursor.screenpos(denops, winid, 1, 1)); assertScreenPos(await cursor.screenpos(denops, "%", 1, 1)); // screenpos() returns `{}` if failed assertEquals( @@ -93,7 +100,14 @@ test({ name: "getcurpos", fn: async () => { await denops.cmd("enew!"); + const winid = await denops.call("bufwinid", "%") as number; + assertPosition(await cursor.getcurpos(denops)); + assertEquals(await cursor.getcurpos(denops), [0, 1, 1, 0, 1]); + assertPosition(await cursor.getcurpos(denops, winid)); + assertEquals(await cursor.getcurpos(denops, winid), [0, 1, 1, 0, 1]); + assertEquals(await cursor.getcurpos(denops, "%"), [0, 1, 1, 0, 1]); + assertEquals(await cursor.getcurpos(denops, -1), [0, 0, 0, 0, 0]); }, }); diff --git a/denops_std/function/getreginfo.ts b/denops_std/function/getreginfo.ts index fbe7bd4c..b6d0bdf1 100644 --- a/denops_std/function/getreginfo.ts +++ b/denops_std/function/getreginfo.ts @@ -51,6 +51,7 @@ export type GetreginfoResult = { * deleted text. * The {regname} argument is a string. If {regname} is invalid * or not set, an empty Dictionary will be returned. + * If {regname} is "" or "@", the unnamed register '"' is used. * If {regname} is not specified, |v:register| is used. * The returned Dictionary can be passed to |setreg()|. * In |Vim9-script| {regname} must be one character. diff --git a/denops_std/function/input.ts b/denops_std/function/input.ts index 25addba6..dc0f838c 100644 --- a/denops_std/function/input.ts +++ b/denops_std/function/input.ts @@ -14,10 +14,12 @@ import { BuiltinCompletion, isValidBuiltinCompletion } from "./types.ts"; * :if input("Coffee or beer? ") == "beer" * : echo "Cheers!" * :endif + * * If the optional {text} argument is present and not empty, this * is used for the default reply, as if the user typed this. * Example: * :let color = input("Color? ", "white") + * * The optional {completion} argument specifies the type of * completion supported for the input. Without it completion is * not performed. The supported completion types are the same as @@ -25,6 +27,7 @@ import { BuiltinCompletion, isValidBuiltinCompletion } from "./types.ts"; * "-complete=" argument. Refer to |:command-completion| for * more information. Example: * let fname = input("File: ", "", "file") + * * NOTE: This function must not be used in a startup file, for * the versions that only run in GUI mode (e.g., the Win32 GUI). * Note: When input() is called from within a mapping it will @@ -34,13 +37,15 @@ import { BuiltinCompletion, isValidBuiltinCompletion } from "./types.ts"; * after input() to avoid that. Another solution is to avoid * that further characters follow in the mapping, e.g., by using * |:execute| or |:normal|. + * * Example with a mapping: - * :nmap \x :call GetFoo():exe "/" . Foo:exe "/" .. Foo * :function GetFoo() * : call inputsave() * : let g:Foo = input("enter search pattern: ") * : call inputrestore() * :endfunction + * * Can also be used as a |method|: * GetPrompt()->input() */ @@ -65,16 +70,18 @@ export function input( * displayed, one string per line. The user will be prompted to * enter a number, which is returned. * The user can also select an item by clicking on it with the - * mouse. For the first string 0 is returned. When clicking - * above the first item a negative number is returned. When - * clicking on the prompt one more than the length of {textlist} - * is returned. + * mouse, if the mouse is enabled in the command line ('mouse' is + * "a" or includes "c"). For the first string 0 is returned. + * When clicking above the first item a negative number is + * returned. When clicking on the prompt one more than the + * length of {textlist} is returned. * Make sure {textlist} has less than 'lines' entries, otherwise * it won't work. It's a good idea to put the entry number at * the start of the string. And put a prompt in the first item. * Example: * let color = inputlist(['Select color:', '1. red', * \ '2. green', '3. blue']) + * * Can also be used as a |method|: * GetChoices()->inputlist() */ @@ -86,10 +93,11 @@ export function inputlist(denops: Denops, textlist: string[]): Promise { * Restore typeahead that was saved with a previous |inputsave()|. * Should be called the same number of times inputsave() is * called. Calling it more often is harmless though. - * Returns 1 when there is nothing to restore, 0 otherwise. + * Returns TRUE when there is nothing to restore, FALSE otherwise. */ -export function inputrestore(denops: Denops): Promise { - return denops.call("inputrestore") as Promise; +export async function inputrestore(denops: Denops): Promise { + const result = await denops.call("inputrestore") as number; + return !!result; } /** @@ -98,10 +106,11 @@ export function inputrestore(denops: Denops): Promise { * followed by a matching inputrestore() after the prompt. Can * be used several times, in which case there must be just as * many inputrestore() calls. - * Returns 1 when out of memory, 0 otherwise. + * Returns TRUE when out of memory, FALSE otherwise. */ -export function inputsave(denops: Denops): Promise { - return denops.call("inputsave") as Promise; +export async function inputsave(denops: Denops): Promise { + const result = await denops.call("inputsave") as number; + return !!result; } /** @@ -114,6 +123,7 @@ export function inputsave(denops: Denops): Promise { * The result is a String, which is whatever the user actually * typed on the command-line in response to the issued prompt. * NOTE: Command-line completion is not supported. + * * Can also be used as a |method|: * GetPrompt()->inputsecret() */ diff --git a/denops_std/function/various.ts b/denops_std/function/various.ts index 988c97de..da9efd74 100644 --- a/denops_std/function/various.ts +++ b/denops_std/function/various.ts @@ -6,7 +6,8 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * a non-empty String (|non-zero-arg|), then the full mode is * returned, otherwise only the first letter is returned. * Also see |state()|. - * n Normal, Terminal-Normal + * + * n Normal * no Operator-pending * nov Operator-pending (forced characterwise |o_v|) * noV Operator-pending (forced linewise |o_V|) @@ -15,9 +16,13 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * niI Normal using |i_CTRL-O| in |Insert-mode| * niR Normal using |i_CTRL-O| in |Replace-mode| * niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| + * nt Terminal-Normal (insert goes to Terminal-Job mode) * v Visual by character + * vs Visual by character using |v_CTRL-O| in Select mode * V Visual by line + * Vs Visual by line using |v_CTRL-O| in Select mode * CTRL-V Visual blockwise + * CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode * s Select by character * S Select by line * CTRL-S Select blockwise @@ -26,8 +31,10 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * ix Insert mode |i_CTRL-X| completion * R Replace |R| * Rc Replace mode completion |compl-generic| - * Rv Virtual Replace |gR| * Rx Replace mode |i_CTRL-X| completion + * Rv Virtual Replace |gR| + * Rvc Virtual Replace mode completion |compl-generic| + * Rvx Virtual Replace mode |i_CTRL-X| completion * c Command-line editing * cv Vim Ex mode |gQ| * ce Normal Ex mode |Q| @@ -36,12 +43,14 @@ import type { Denops } from "https://deno.land/x/denops_core@v4.0.0/mod.ts"; * r? A |:confirm| query of some sort * ! Shell or external command is executing * t Terminal-Job mode: keys go to the job + * * This is useful in the 'statusline' option or when used * with |remote_expr()| In most other places it always returns * "c" or "n". * Note that in the future more modes and more specific modes may * be added. It's better not to compare the whole string but only * the leading character(s). + * * Also see |visualmode()|. * Can also be used as a |method|: * DoFull()->mode() diff --git a/denops_std/function/vim/prop_add_list.ts b/denops_std/function/vim/prop_add_list.ts index 9770d3e0..adf12ce7 100644 --- a/denops_std/function/vim/prop_add_list.ts +++ b/denops_std/function/vim/prop_add_list.ts @@ -6,11 +6,17 @@ export type PropAddListProps = { type: string; }; -export type PropAddListItem = [number, number, number, number]; +export type PropAddListItem = [ + lnum: number, + col: number, + end_lnum: number, + end_col: number, +]; /** * Similar to prop_add(), but attaches a text property at * multiple positions in a buffer. + * * {props} is a dictionary with these fields: * bufnr buffer to add the property to; when omitted * the current buffer is used @@ -18,17 +24,23 @@ export type PropAddListItem = [number, number, number, number]; * number; when omitted zero is used * type name of the text property type * All fields except "type" are optional. + * * The second argument is a List of Lists where each list * specifies the starting and ending position of the text. The * first two items {lnum} and {col} specify the starting position * of the text where the property will be attached and the last * two items {end-lnum} and {end-col} specify the position just * after the text. + * + * It is not possible to add a text property with a "text" field + * here. + * * Example: * call prop_add_list(#{type: 'MyProp', id: 2}, * \ [[1, 4, 1, 7], * \ [1, 15, 1, 20], * \ [2, 30, 3, 30]] + * * Can also be used as a |method|: * GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]]) */