diff options
Diffstat (limited to 'src/nvim/eval.lua')
| -rw-r--r-- | src/nvim/eval.lua | 125 |
1 files changed, 89 insertions, 36 deletions
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index b7120d5dd5..7d4438ded6 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -2071,14 +2071,13 @@ M.funcs = { The result is a Number: 1 exists 0 does not exist - -1 not implemented on this system |exepath()| can be used to get the full path of an executable. ]=], fast = true, name = 'executable', params = { { 'expr', 'any' } }, - returns = '0|1|-1', + returns = '0|1', signature = 'executable({expr})', }, execute = { @@ -2481,6 +2480,7 @@ M.funcs = { 't' Handle keys as if typed; otherwise they are handled as if coming from a mapping. This matters for undo, opening folds, etc. + 'L' Lowlevel input. Other flags are not used. 'i' Insert the string instead of appending (see above). 'x' Execute commands until typeahead is empty. This is similar to using ":normal!". You can call feedkeys() @@ -3383,14 +3383,14 @@ M.funcs = { args = { 0, 1 }, desc = [=[ Get a single character from the user or input stream. - If [expr] is omitted, wait until a character is available. - If [expr] is 0, only get a character when one is available. + If {expr} is omitted, wait until a character is available. + If {expr} is 0, only get a character when one is available. Return zero otherwise. - If [expr] is 1, only check if a character is available, it is + If {expr} is 1, only check if a character is available, it is not consumed. Return zero if no character available. If you prefer always getting a string use |getcharstr()|. - Without [expr] and when [expr] is 0 a whole character or + Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the result is a Number. Use |nr2char()| to convert it to a String. Otherwise a String is returned with the encoded character. @@ -3400,11 +3400,11 @@ M.funcs = { also a String when a modifier (shift, control, alt) was used that is not included in the character. - When [expr] is 0 and Esc is typed, there will be a short delay + When {expr} is 0 and Esc is typed, there will be a short delay while Vim waits to see if this is the start of an escape sequence. - When [expr] is 1 only the first byte is returned. For a + When {expr} is 1 only the first byte is returned. For a one-byte character it is the character itself as a number. Use nr2char() to convert it to a String. @@ -3449,7 +3449,7 @@ M.funcs = { name = 'getchar', params = {}, returns = 'integer', - signature = 'getchar([expr])', + signature = 'getchar([{expr}])', }, getcharmod = { desc = [=[ @@ -3526,10 +3526,10 @@ M.funcs = { desc = [=[ Get a single character from the user or input stream as a string. - If [expr] is omitted, wait until a character is available. - If [expr] is 0 or false, only get a character when one is + If {expr} is omitted, wait until a character is available. + If {expr} is 0 or false, only get a character when one is available. Return an empty string otherwise. - If [expr] is 1 or true, only check if a character is + If {expr} is 1 or true, only check if a character is available, it is not consumed. Return an empty string if no character is available. Otherwise this works like |getchar()|, except that a number @@ -3538,7 +3538,7 @@ M.funcs = { name = 'getcharstr', params = {}, returns = 'string', - signature = 'getcharstr([expr])', + signature = 'getcharstr([{expr}])', }, getcmdcompltype = { desc = [=[ @@ -4414,6 +4414,46 @@ M.funcs = { returns = 'string[]', signature = 'getregion({pos1}, {pos2} [, {opts}])', }, + getregionpos = { + args = { 2, 3 }, + base = 1, + desc = [=[ + Same as |getregion()|, but returns a list of positions + describing the buffer text segments bound by {pos1} and + {pos2}. + The segments are a pair of positions for every line: > + [[{start_pos}, {end_pos}], ...] + < + The position is a |List| with four numbers: + [bufnum, lnum, col, off] + "bufnum" is the buffer number. + "lnum" and "col" are the position in the buffer. The first + column is 1. + 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 <Tab> 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|) + ]=], + name = 'getregionpos', + params = { { 'pos1', 'table' }, { 'pos2', 'table' }, { 'opts', 'table' } }, + returns = 'integer[][][]', + signature = 'getregionpos({pos1}, {pos2} [, {opts}])', + }, getregtype = { args = { 0, 1 }, base = 1, @@ -4470,11 +4510,12 @@ M.funcs = { Examples: >vim echo getscriptinfo({'name': 'myscript'}) - echo getscriptinfo({'sid': 15}).variables + echo getscriptinfo({'sid': 15})[0].variables < ]=], name = 'getscriptinfo', params = { { 'opts', 'table' } }, + returns = 'vim.fn.getscriptinfo.ret[]', signature = 'getscriptinfo([{opts}])', }, gettabinfo = { @@ -4905,6 +4946,7 @@ M.funcs = { endif < ]=], + fast = true, name = 'has', params = { { 'feature', 'any' } }, returns = '0|1', @@ -7249,7 +7291,7 @@ M.funcs = { base = 1, desc = [=[ Return a string that indicates the current mode. - If [expr] is supplied and it evaluates to a non-zero Number or + If {expr} is supplied and it evaluates to a non-zero Number or a non-empty String (|non-zero-arg|), then the full mode is returned, otherwise only the first letter is returned. Also see |state()|. @@ -7304,7 +7346,7 @@ M.funcs = { ]=], name = 'mode', params = { { 'expr', 'any' } }, - signature = 'mode([expr])', + signature = 'mode([{expr}])', }, msgpackdump = { args = { 1, 2 }, @@ -7836,6 +7878,9 @@ M.funcs = { echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) < 1.41 + You will get an overflow error |E1510|, when the field-width + or precision will result in a string longer than 6400 chars. + *E1500* You cannot mix positional and non-positional arguments: >vim echo printf("%s%1$s", "One", "Two") @@ -7898,6 +7943,7 @@ M.funcs = { name = 'printf', params = { { 'fmt', 'any' }, { 'expr1', 'any' } }, signature = 'printf({fmt}, {expr1} ...)', + returns = 'string', }, prompt_getprompt = { args = 1, @@ -8746,6 +8792,7 @@ M.funcs = { When a match has been found its line number is returned. If there is no match a 0 is returned and the cursor doesn't move. No error message is given. + To get the matched string, use |matchbufline()|. {flags} is a String, which can contain these character flags: 'b' search Backward instead of forward @@ -9896,10 +9943,11 @@ M.funcs = { Otherwise encloses {string} in single-quotes and replaces all "'" with "'\''". - If {special} is a |non-zero-arg|: - - Special items such as "!", "%", "#" and "<cword>" will be - preceded by a backslash. The backslash will be removed again - by the |:!| command. + The {special} argument adds additional escaping of keywords + used in Vim commands. If it is a |non-zero-arg|: + - Special items such as "!", "%", "#" and "<cword>" (as listed + in |expand()|) will be preceded by a backslash. + The backslash will be removed again by the |:!| command. - The <NL> character is escaped. If 'shell' contains "csh" in the tail: @@ -10481,7 +10529,8 @@ M.funcs = { 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. - Also, composing characters are not counted. + 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. @@ -10953,8 +11002,8 @@ M.funcs = { of byte index and length. When {skipcc} is omitted or zero, composing characters are counted separately. - When {skipcc} set to 1, Composing characters are ignored, - similar to |slice()|. + When {skipcc} set to 1, composing characters are treated as a + part of the preceding base character, similar to |slice()|. When a character index is used where a character does not exist it is omitted and counted as one character. For example: >vim @@ -10977,7 +11026,7 @@ M.funcs = { in String {string}. When {skipcc} is omitted or zero, composing characters are counted separately. - When {skipcc} set to 1, Composing characters are ignored. + When {skipcc} set to 1, composing characters are ignored. |strcharlen()| always does this. Returns zero on error. @@ -11124,10 +11173,10 @@ M.funcs = { for infinite and NaN floating-point values representations which use |str2float()|. Strings are also dumped literally, only single quote is escaped, which does not allow using YAML - for parsing back binary strings. |eval()| should always work for - strings and floats though and this is the only official - method, use |msgpackdump()| or |json_encode()| if you need to - share data with other application. + for parsing back binary strings. |eval()| should always work + for strings and floats though, and this is the only official + method. Use |msgpackdump()| or |json_encode()| if you need to + share data with other applications. ]=], name = 'string', @@ -11615,6 +11664,10 @@ M.funcs = { synconcealed(lnum, 4) [1, 'X', 2] synconcealed(lnum, 5) [1, 'X', 2] synconcealed(lnum, 6) [0, '', 0] + + Note: Doesn't consider |matchadd()| highlighting items, + since syntax and matching highlighting are two different + mechanisms |syntax-vs-match|. ]=], name = 'synconcealed', params = { { 'lnum', 'integer' }, { 'col', 'integer' } }, @@ -12687,9 +12740,7 @@ M.funcs = { [1, 1], unless there is a tabline, then it is [2, 1]. {nr} can be the window number or the |window-ID|. Use zero for the current window. - Returns [0, 0] if the window cannot be found in the current - tabpage. - + Returns [0, 0] if the window cannot be found. ]=], name = 'win_screenpos', params = { { 'nr', 'integer' } }, @@ -12699,10 +12750,10 @@ M.funcs = { args = { 2, 3 }, base = 1, desc = [=[ - Move the window {nr} to a new split of the window {target}. - This is similar to moving to {target}, creating a new window - using |:split| but having the same contents as window {nr}, and - then closing {nr}. + Temporarily switch to window {target}, then move window {nr} + to a new split adjacent to {target}. + Unlike commands such as |:split|, no new windows are created + (the |window-ID| of window {nr} is unchanged after the move). Both {nr} and {target} can be window numbers or |window-ID|s. Both must be in the current tab page. @@ -12856,7 +12907,9 @@ M.funcs = { # the number of the last accessed window (where |CTRL-W_p| goes to). If there is no previous window or it is in another tab page 0 is - returned. + returned. May refer to the current window in + some cases (e.g. when evaluating 'statusline' + expressions). {N}j the number of the Nth window below the current window (where |CTRL-W_j| goes to). {N}k the number of the Nth window above the current |