aboutsummaryrefslogtreecommitdiff
path: root/src/nvim/eval.lua
diff options
context:
space:
mode:
Diffstat (limited to 'src/nvim/eval.lua')
-rw-r--r--src/nvim/eval.lua13263
1 files changed, 12811 insertions, 452 deletions
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 9a5ab51c71..55f4721c3a 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -2,462 +2,12821 @@
--
-- Keys:
--
--- args Number of arguments, list with maximum and minimum number of arguments
--- or list with a minimum number of arguments only. Defaults to zero
--- arguments.
--- base For methods: the argument to use as the base argument (1-indexed):
--- base->method()
--- Defaults to BASE_NONE (function cannot be used as a method).
--- func Name of the C function which implements the VimL function. Defaults to
--- `f_{funcname}`.
--- fast Function can run in |api-fast| events. Defaults to false.
-
-local varargs = function(nr)
- return {nr}
-end
+--- @class vim.EvalFn
+--- @field name? string
+--- @field args? integer|integer[] Number of arguments, list with maximum and minimum number of arguments
+--- or list with a minimum number of arguments only. Defaults to zero
+--- arguments.
+--- @field base? integer For methods: the argument to use as the base argument (1-indexed):
+--- base->method()
+--- Defaults to BASE_NONE (function cannot be used as a method).
+--- @field func? string Name of the C function which implements the Vimscript function. Defaults to
+--- `f_{funcname}`.
+--- @field float_func? string
+--- @field fast? boolean Function can run in |api-fast| events. Defaults to false.
+--- @field deprecated? true
+--- @field returns? string|false
+--- @field returns_desc? string
+--- @field signature string
+--- @field desc? string
+--- @field params {[1]:string, [2]:string, [3]:string}[]
+--- @field lua? false Do not render type information
+--- @field tags? string[] Extra tags
+--- @field data? string Used by gen_eval.lua
-- Usable with the base key: use the last function argument as the method base.
-- Value is from funcs.h file. "BASE_" prefix is omitted.
-- local LAST = "BASE_LAST" (currently unused after port of v8.2.1168)
-return {
- funcs={
- abs={args=1, base=1},
- acos={args=1, base=1, float_func="acos"}, -- WJMc
- add={args=2, base=1},
- ['and']={args=2, base=1},
- api_info={fast=true},
- append={args=2, base=2},
- appendbufline={args=3, base=3},
- argc={args={0, 1}},
- argidx={},
- arglistid={args={0, 2}},
- argv={args={0, 2}},
- asin={args=1, base=1, float_func="asin"}, -- WJMc
- assert_beeps={args=1, base=1},
- assert_equal={args={2, 3}, base=2},
- assert_equalfile={args={2, 3}, base=1},
- assert_exception={args={1, 2}},
- assert_fails={args={1, 5}, base=1},
- assert_false={args={1, 2}, base=1},
- assert_inrange={args={3, 4}, base=3},
- assert_match={args={2, 3}, base=2},
- assert_nobeep={args=1, base=1},
- assert_notequal={args={2, 3}, base=2},
- assert_notmatch={args={2, 3}, base=2},
- assert_report={args=1, base=1},
- assert_true={args={1, 2}, base=1},
- atan={args=1, base=1, float_func="atan"},
- atan2={args=2, base=1},
- browse={args=4},
- browsedir={args=2},
- bufadd={args=1, base=1},
- bufexists={args=1, base=1},
- buffer_exists={args=1, base=1, func='f_bufexists'}, -- obsolete
- buffer_name={args={0, 1}, base=1, func='f_bufname'}, -- obsolete
- buffer_number={args={0, 1}, base=1, func='f_bufnr'}, -- obsolete
- buflisted={args=1, base=1},
- bufload={args=1, base=1},
- bufloaded={args=1, base=1},
- bufname={args={0, 1}, base=1},
- bufnr={args={0, 2}, base=1},
- bufwinid={args=1, base=1},
- bufwinnr={args=1, base=1},
- byte2line={args=1, base=1},
- byteidx={args=2, base=1, fast=true},
- byteidxcomp={args=2, base=1, fast=true},
- call={args={2, 3}, base=1},
- ceil={args=1, base=1, float_func="ceil"},
- changenr={},
- chanclose={args={1, 2}},
- chansend={args=2},
- char2nr={args={1, 2}, base=1, fast=true},
- charclass={args=1, base=1},
- charcol={args={1, 2}, base=1},
- charidx={args={2, 3}, base=1},
- chdir={args=1, base=1},
- cindent={args=1, base=1},
- clearmatches={args={0, 1}, base=1},
- col={args={1, 2}, base=1},
- complete={args=2, base=2},
- complete_add={args=1, base=1},
- complete_check={},
- complete_info={args={0, 1}, base=1},
- confirm={args={1, 4}, base=1},
- copy={args=1, base=1},
- cos={args=1, base=1, float_func="cos"},
- cosh={args=1, base=1, float_func="cosh"},
- count={args={2, 4}, base=1},
- ctxget={args={0, 1}},
- ctxpop={},
- ctxpush={args={0, 1}},
- ctxset={args={1, 2}},
- ctxsize={},
- cursor={args={1, 3}, base=1},
- debugbreak={args={1, 1}, base=1},
- deepcopy={args={1, 2}, base=1},
- delete={args={1,2}, base=1},
- deletebufline={args={2,3}, base=1},
- dictwatcheradd={args=3},
- dictwatcherdel={args=3},
- did_filetype={fast=true},
- diff_filler={args=1, base=1},
- diff_hlID={args=2, base=1},
- digraph_get={args=1, base=1},
- digraph_getlist={args={0, 1}, base=1},
- digraph_set={args=2, base=1},
- digraph_setlist={args=1, base=1},
- empty={args=1, base=1},
- environ={fast=true},
- escape={args=2, base=1, fast=true},
- eval={args=1, base=1},
- eventhandler={},
- executable={args=1, base=1, fast=true},
- execute={args={1, 2}, base=1},
- exepath={args=1, base=1},
- exists={args=1, base=1},
- exp={args=1, base=1, float_func="exp"},
- expand={args={1, 3}, base=1},
- expandcmd={args={1, 2}, base=1},
- extend={args={2, 3}, base=1},
- feedkeys={args={1, 2}, base=1},
- file_readable={args=1, base=1, func='f_filereadable'}, -- obsolete
- filereadable={args=1, base=1, fast=true},
- filewritable={args=1, base=1, fast=true},
- filter={args=2, base=1},
- finddir={args={1, 3}, base=1},
- findfile={args={1, 3}, base=1},
- flatten={args={1, 2}, base=1},
- float2nr={args=1, base=1},
- floor={args=1, base=1, float_func="floor"},
- fmod={args=2, base=1},
- fnameescape={args=1, base=1, fast=true},
- fnamemodify={args=2, base=1, fast=true},
- foldclosed={args=1, base=1},
- foldclosedend={args=1, base=1},
- foldlevel={args=1, base=1},
- foldtext={},
- foldtextresult={args=1, base=1},
- foreground={},
- fullcommand={args=1, base=1},
- funcref={args={1, 3}, base=1},
- ['function']={args={1, 3}, base=1},
- garbagecollect={args={0, 1}},
- get={args={2, 3}, base=1},
- getbufinfo={args={0, 1}, base=1},
- getbufline={args={2, 3}, base=1},
- getbufoneline={args=2, base=1},
- getbufvar={args={2, 3}, base=1},
- getcellwidths={},
- getchangelist={args={0, 1}, base=1},
- getchar={args={0, 1}},
- getcharmod={},
- getcharpos={args=1, base=1},
- getcharsearch={},
- getcharstr={args={0, 1}},
- getcmdcompltype={},
- getcmdline={},
- getcmdpos={},
- getcmdscreenpos={},
- getcmdtype={},
- getcmdwintype={},
- getcompletion={args={2, 3}, base=1},
- getcurpos={args={0, 1}, base=1},
- getcursorcharpos={args={0, 1}, base=1},
- getcwd={args={0, 2}, base=1},
- getenv={args=1, base=1},
- getfontname={args={0, 1}},
- getfperm={args=1, base=1, fast=true},
- getfsize={args=1, base=1, fast=true},
- getftime={args=1, base=1, fast=true},
- getftype={args=1, base=1, fast=true},
- getjumplist={args={0, 2}, base=1},
- getline={args={1, 2}, base=1},
- getloclist={args={1, 2}},
- getmarklist={args={0, 1}, base=1},
- getmatches={args={0, 1}},
- getmousepos={},
- getpid={fast=true},
- getpos={args=1, base=1},
- getqflist={args={0, 1}},
- getreg={args={0, 3}, base=1},
- getreginfo={args={0, 1}, base=1},
- getregtype={args={0, 1}, base=1},
- gettabinfo={args={0, 1}, base=1},
- gettabvar={args={2, 3}, base=1},
- gettabwinvar={args={3, 4}, base=1},
- gettagstack={args={0, 1}, base=1},
- gettext={args=1, base=1},
- getwininfo={args={0, 1}, base=1},
- getwinpos={args={0, 1}, base=1},
- getwinposx={},
- getwinposy={},
- getwinvar={args={2, 3}, base=1},
- glob={args={1, 4}, base=1},
- glob2regpat={args=1, base=1},
- globpath={args={2, 5}, base=2},
- has={args=1},
- has_key={args=2, base=1},
- haslocaldir={args={0, 2}, base=1},
- hasmapto={args={1, 3}, base=1},
- highlightID={args=1, base=1, func='f_hlID'}, -- obsolete
- highlight_exists={args=1, base=1, func='f_hlexists'}, -- obsolete
- histadd={args=2, base=2},
- histdel={args={1, 2}, base=1},
- histget={args={1, 2}, base=1},
- histnr={args=1, base=1},
- hlID={args=1, base=1},
- hlexists={args=1, base=1},
- hostname={fast=true},
- iconv={args=3, base=1, fast=true},
- indent={args=1, base=1},
- index={args={2, 4}, base=1},
- input={args={1, 3}, base=1},
- inputdialog={args={1, 3}, base=1},
- inputlist={args=1, base=1},
- inputrestore={},
- inputsave={},
- inputsecret={args={1, 2}, base=1},
- insert={args={2, 3}, base=1},
- interrupt={args=0},
- invert={args=1, base=1},
- isdirectory={args=1, base=1, fast=true},
- isinf={args=1, base=1},
- islocked={args=1, base=1},
- isnan={args=1, base=1},
- id={args=1},
- items={args=1, base=1},
- jobclose={args={1, 2}, func="f_chanclose"},
- jobpid={args=1},
- jobresize={args=3},
- jobsend={args=2, func="f_chansend"},
- jobstart={args={1, 2}},
- jobstop={args=1},
- jobwait={args={1, 2}},
- join={args={1, 2}, base=1},
- json_decode={args=1, base=1},
- json_encode={args=1, base=1},
- keys={args=1, base=1},
- keytrans={args=1, base=1},
- last_buffer_nr={}, -- obsolete
- len={args=1, base=1},
- libcall={args=3, base=3},
- libcallnr={args=3, base=3},
- line={args={1, 2}, base=1},
- line2byte={args=1, base=1},
- lispindent={args=1, base=1},
- list2str={args={1, 2}, base=1},
- localtime={},
- log={args=1, base=1, float_func="log"},
- log10={args=1, base=1, float_func="log10"},
- luaeval={args={1, 2}, base=1},
- map={args=2, base=1},
- maparg={args={1, 4}, base=1},
- mapcheck={args={1, 3}, base=1},
- mapset={args=3, base=1},
- match={args={2, 4}, base=1},
- matchadd={args={2, 5}, base=1},
- matchaddpos={args={2, 5}, base=1},
- matcharg={args=1, base=1},
- matchdelete={args={1, 2}, base=1},
- matchend={args={2, 4}, base=1},
- matchfuzzy={args={2, 3}, base=1},
- matchfuzzypos={args={2, 3}, base=1},
- matchlist={args={2, 4}, base=1},
- matchstr={args={2, 4}, base=1},
- matchstrpos={args={2,4}, base=1},
- max={args=1, base=1},
- menu_get={args={1, 2}},
- menu_info={args={1, 2}, base=1},
- min={args=1, base=1},
- mkdir={args={1, 3}, base=1},
- mode={args={0, 1}, base=1},
- msgpackdump={args={1, 2}},
- msgpackparse={args=1},
- nextnonblank={args=1, base=1},
- nr2char={args={1, 2}, base=1},
- ['or']={args=2, base=1},
- pathshorten={args={1, 2}, base=1},
- pow={args=2, base=1},
- prevnonblank={args=1, base=1},
- printf={args=varargs(1), base=2},
- prompt_getprompt={args=1, base=1},
- prompt_setcallback={args={2, 2}, base=1},
- prompt_setinterrupt={args={2, 2}, base=1},
- prompt_setprompt={args={2, 2}, base=1},
- pum_getpos={},
- pumvisible={},
- py3eval={args=1, base=1},
- pyeval={args=1, base=1, func="f_py3eval"},
- pyxeval={args=1, base=1, func="f_py3eval"},
- perleval={args=1, base=1},
- rand={args={0, 1}, base=1},
- range={args={1, 3}, base=1},
- readblob={args=1, base=1},
- readdir={args={1, 2}, base=1},
- readfile={args={1, 3}, base=1},
- reduce={args={2, 3}, base=1},
- reg_executing={},
- reg_recording={},
- reg_recorded={},
- reltime={args={0, 2}, base=1, fast=true},
- reltimefloat={args=1, base=1, fast=true},
- reltimestr={args=1, base=1, fast=true},
- remove={args={2, 3}, base=1},
- rename={args=2, base=1},
- ['repeat']={args=2, base=1, fast=true},
- resolve={args=1, base=1, fast=true},
- reverse={args=1, base=1},
- round={args=1, base=1, float_func="round"},
- rpcnotify={args=varargs(2)},
- rpcrequest={args=varargs(2)},
- rpcstart={args={1, 2}},
- rpcstop={args=1},
- rubyeval={args=1, base=1},
- screenattr={args=2, base=1},
- screenchar={args=2, base=1},
- screenchars={args=2, base=1},
- screencol={},
- screenpos={args=3, base=1},
- screenrow={},
- screenstring={args=2, base=1},
- search={args={1, 5}, base=1},
- searchcount={args={0, 1}, base=1},
- searchdecl={args={1, 3}, base=1},
- searchpair={args={3, 7}},
- searchpairpos={args={3, 7}},
- searchpos={args={1, 5}, base=1},
- serverlist={},
- serverstart={args={0, 1}},
- serverstop={args=1},
- setbufline={args=3, base=3},
- setbufvar={args=3, base=3},
- setcellwidths={args=1, base=1},
- setcharpos={args=2, base=2},
- setcharsearch={args=1, base=1},
- setcmdpos={args=1, base=1},
- setcmdline={args={1, 2}, base=1},
- setcursorcharpos={args={1, 3}, base=1},
- setenv={args=2, base=2},
- setfperm={args=2, base=1},
- setline={args=2, base=2},
- setloclist={args={2, 4}, base=2},
- setmatches={args={1, 2}, base=1},
- setpos={args=2, base=2},
- setqflist={args={1, 3}, base=1},
- setreg={args={2, 3}, base=2},
- settabvar={args=3, base=3},
- settabwinvar={args=4, base=4},
- settagstack={args={2, 3}, base=2},
- setwinvar={args=3, base=3},
- sha256={args=1, base=1},
- shellescape={args={1, 2}, base=1},
- shiftwidth={args={0, 1}, base=1},
- sign_define={args={1, 2}, base=1},
- sign_getdefined={args={0, 1}, base=1},
- sign_getplaced={args={0, 2}, base=1},
- sign_jump={args=3, base=1},
- sign_place={args={4, 5}, base=1},
- sign_placelist={args=1, base=1},
- sign_undefine={args={0, 1}, base=1},
- sign_unplace={args={1, 2}, base=1},
- sign_unplacelist={args=1, base=1},
- simplify={args=1, base=1},
- sin={args=1, base=1, float_func="sin"},
- sinh={args=1, base=1, float_func="sinh"},
- sockconnect={args={2,3}},
- sort={args={1, 3}, base=1},
- soundfold={args=1, base=1},
- stdioopen={args=1},
- spellbadword={args={0, 1}, base=1},
- spellsuggest={args={1, 3}, base=1},
- split={args={1, 3}, base=1},
- sqrt={args=1, base=1, float_func="sqrt"},
- srand={args={0, 1}, base=1},
- stdpath={args=1, fast=true},
- str2float={args=1, base=1},
- str2list={args={1, 2}, base=1},
- str2nr={args={1, 3}, base=1},
- strcharlen={args=1, base=1},
- strcharpart={args={2, 3}, base=1, fast=true},
- strchars={args={1, 2}, base=1},
- strdisplaywidth={args={1, 2}, base=1},
- strftime={args={1, 2}, base=1},
- strgetchar={args=2, base=1},
- stridx={args={2, 3}, base=1, fast=true},
- string={args=1, base=1},
- strlen={args=1, base=1},
- strpart={args={2, 4}, base=1, fast=true},
- strptime={args=2, base=1},
- strridx={args={2, 3}, base=1},
- strtrans={args=1, base=1, fast=true},
- strwidth={args=1, base=1, fast=true},
- submatch={args={1, 2}, base=1},
- substitute={args=4, base=1},
- swapinfo={args=1, base=1},
- swapname={args=1, base=1},
- synID={args=3},
- synIDattr={args={2, 3}, base=1},
- synIDtrans={args=1, base=1},
- synconcealed={args=2},
- synstack={args=2},
- system={args={1, 2}, base=1},
- systemlist={args={1, 3}, base=1},
- tabpagebuflist={args={0, 1}, base=1},
- tabpagenr={args={0, 1}},
- tabpagewinnr={args={1, 2}, base=1},
- tagfiles={},
- taglist={args={1, 2}, base=1},
- tan={args=1, base=1, float_func="tan"},
- tanh={args=1, base=1, float_func="tanh"},
- tempname={},
- termopen={args={1, 2}},
- test_garbagecollect_now={},
- test_write_list_log={args=1},
- timer_info={args={0, 1}, base=1},
- timer_pause={args=2, base=1},
- timer_start={args={2, 3}, base=1},
- timer_stop={args=1, base=1},
- timer_stopall={args=0},
- tolower={args=1, base=1, fast=true},
- toupper={args=1, base=1, fast=true},
- tr={args=3, base=1},
- trim={args={1, 3}, base=1},
- trunc={args=1, base=1, float_func="trunc"},
- type={args=1, base=1, fast=true},
- undofile={args=1, base=1},
- undotree={},
- uniq={args={1, 3}, base=1},
- values={args=1, base=1},
- virtcol={args=1, base=1},
- virtcol2col={args=3, base=1},
- visualmode={args={0, 1}},
- wait={args={2,3}},
- wildmenumode={},
- win_execute={args={2, 3}, base=2},
- win_findbuf={args=1, base=1},
- win_getid={args={0, 2}, base=1},
- win_gettype={args={0, 1}, base=1},
- win_gotoid={args=1, base=1},
- win_id2tabwin={args=1, base=1},
- win_id2win={args=1, base=1},
- win_move_separator={args=2, base=1},
- win_move_statusline={args=2, base=1},
- win_screenpos={args=1, base=1},
- win_splitmove={args={2, 3}, base=1},
- winbufnr={args=1, base=1},
- wincol={},
- windowsversion={fast=true},
- winheight={args=1, base=1},
- winlayout={args={0, 1}, base=1},
- winline={},
- winnr={args={0, 1}, base=1},
- winrestcmd={},
- winrestview={args=1, base=1},
- winsaveview={},
- winwidth={args=1, base=1},
- wordcount={},
- writefile={args={2, 3}, base=1},
- xor={args=2, base=1},
+local M = {}
+
+local VARARGS = { { '...', 'any' } }
+
+--- @type table<string,vim.EvalFn>
+M.funcs = {
+ abs = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Return the absolute value of {expr}. When {expr} evaluates to
+ a |Float| abs() returns a |Float|. When {expr} can be
+ converted to a |Number| abs() returns a |Number|. Otherwise
+ abs() gives an error message and returns -1.
+ Examples: >vim
+ echo abs(1.456)
+ < 1.456 >vim
+ echo abs(-5.456)
+ < 5.456 >vim
+ echo abs(-4)
+ < 4
+
+ ]=],
+ name = 'abs',
+ params = { { 'expr', 'any' } },
+ signature = 'abs({expr})',
+ returns = 'number',
+ },
+ acos = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Return the arc cosine of {expr} measured in radians, as a
+ |Float| in the range of [0, pi].
+ {expr} must evaluate to a |Float| or a |Number| in the range
+ [-1, 1].
+ Returns NaN if {expr} is outside the range [-1, 1]. Returns
+ 0.0 if {expr} is not a |Float| or a |Number|.
+ Examples: >vim
+ echo acos(0)
+ < 1.570796 >vim
+ echo acos(-0.5)
+ < 2.094395
+
+ ]=],
+ float_func = 'acos',
+ name = 'acos',
+ params = { { 'expr', 'any' } },
+ returns = 'number',
+ signature = 'acos({expr})',
+ },
+ add = {
+ args = 2,
+ base = 1,
+ desc = [=[
+ Append the item {expr} to |List| or |Blob| {object}. Returns
+ the resulting |List| or |Blob|. Examples: >vim
+ let alist = add([1, 2, 3], item)
+ call add(mylist, "woodstock")
+ <Note that when {expr} is a |List| it is appended as a single
+ item. Use |extend()| to concatenate |Lists|.
+ When {object} is a |Blob| then {expr} must be a number.
+ Use |insert()| to add an item at another position.
+ Returns 1 if {object} is not a |List| or a |Blob|.
+
+ ]=],
+ name = 'add',
+ params = { { 'object', 'any' }, { 'expr', 'any' } },
+ returns = 'any',
+ signature = 'add({object}, {expr})',
+ },
+ ['and'] = {
+ args = 2,
+ base = 1,
+ desc = [=[
+ Bitwise AND on the two arguments. The arguments are converted
+ to a number. A List, Dict or Float argument causes an error.
+ Also see `or()` and `xor()`.
+ Example: >vim
+ let flag = and(bits, 0x80)
+ <
+ ]=],
+ name = 'and',
+ params = { { 'expr', 'any' }, { 'expr', 'any' } },
+ returns = 'integer',
+ signature = 'and({expr}, {expr})',
+ },
+ api_info = {
+ desc = [=[
+ Returns Dictionary of |api-metadata|.
+
+ View it in a nice human-readable format: >vim
+ lua vim.print(vim.fn.api_info())
+ <
+ ]=],
+ fast = true,
+ name = 'api_info',
+ params = {},
+ returns = 'table',
+ signature = 'api_info()',
+ },
+ append = {
+ args = 2,
+ base = 2,
+ desc = [=[
+ When {text} is a |List|: Append each item of the |List| as a
+ text line below line {lnum} in the current buffer.
+ Otherwise append {text} as one text line below line {lnum} in
+ the current buffer.
+ Any type of item is accepted and converted to a String.
+ {lnum} can be zero to insert a line before the first one.
+ {lnum} is used like with |getline()|.
+ Returns 1 for failure ({lnum} out of range or out of memory),
+ 0 for success. When {text} is an empty list zero is returned,
+ no matter the value of {lnum}. Example: >vim
+ let failed = append(line('$'), "# THE END")
+ let failed = append(0, ["Chapter 1", "the beginning"])
+ <
+
+ ]=],
+ name = 'append',
+ params = { { 'lnum', 'integer' }, { 'text', 'any' } },
+ returns = '0|1',
+ signature = 'append({lnum}, {text})',
+ },
+ appendbufline = {
+ args = 3,
+ base = 3,
+ desc = [=[
+ Like |append()| but append the text in buffer {expr}.
+
+ This function works only for loaded buffers. First call
+ |bufload()| if needed.
+
+ For the use of {buf}, see |bufname()|.
+
+ {lnum} is the line number to append below. Note that using
+ |line()| would use the current buffer, not the one appending
+ to. Use "$" to append at the end of the buffer. Other string
+ values are not supported.
+
+ On success 0 is returned, on failure 1 is returned.
+
+ If {buf} is not a valid buffer or {lnum} is not valid, an
+ error message is given. Example: >vim
+ let failed = appendbufline(13, 0, "# THE START")
+ <However, when {text} is an empty list then no error is given
+ for an invalid {lnum}, since {lnum} isn't actually used.
+
+ ]=],
+ name = 'appendbufline',
+ params = { { 'buf', 'any' }, { 'lnum', 'integer' }, { 'text', 'string' } },
+ returns = '0|1',
+ signature = 'appendbufline({buf}, {lnum}, {text})',
+ },
+ argc = {
+ args = { 0, 1 },
+ desc = [=[
+ The result is the number of files in the argument list. See
+ |arglist|.
+ If {winid} is not supplied, the argument list of the current
+ window is used.
+ If {winid} is -1, the global argument list is used.
+ Otherwise {winid} specifies the window of which the argument
+ list is used: either the window number or the window ID.
+ Returns -1 if the {winid} argument is invalid.
+ ]=],
+ name = 'argc',
+ params = { { 'winid', 'integer' } },
+ returns = 'integer',
+ signature = 'argc([{winid}])',
+ },
+ argidx = {
+ desc = [=[
+ The result is the current index in the argument list. 0 is
+ the first file. argc() - 1 is the last one. See |arglist|.
+ ]=],
+ name = 'argidx',
+ params = {},
+ returns = 'integer',
+ signature = 'argidx()',
+ },
+ arglistid = {
+ args = { 0, 2 },
+ desc = [=[
+ Return the argument list ID. This is a number which
+ identifies the argument list being used. Zero is used for the
+ global argument list. See |arglist|.
+ Returns -1 if the arguments are invalid.
+
+ Without arguments use the current window.
+ With {winnr} only use this window in the current tab page.
+ With {winnr} and {tabnr} use the window in the specified tab
+ page.
+ {winnr} can be the window number or the |window-ID|.
+ ]=],
+ name = 'arglistid',
+ params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } },
+ returns = 'integer',
+ signature = 'arglistid([{winnr} [, {tabnr}]])',
+ },
+ argv = {
+ args = { 0, 2 },
+ desc = [=[
+ The result is the {nr}th file in the argument list. See
+ |arglist|. "argv(0)" is the first one. Example: >vim
+ let i = 0
+ while i < argc()
+ let f = escape(fnameescape(argv(i)), '.')
+ exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>'
+ let i = i + 1
+ endwhile
+ <Without the {nr} argument, or when {nr} is -1, a |List| with
+ the whole |arglist| is returned.
+
+ The {winid} argument specifies the window ID, see |argc()|.
+ For the Vim command line arguments see |v:argv|.
+
+ Returns an empty string if {nr}th argument is not present in
+ the argument list. Returns an empty List if the {winid}
+ argument is invalid.
+ ]=],
+ name = 'argv',
+ params = { { 'nr', 'integer' }, { 'winid', 'integer' } },
+ returns = 'string|string[]',
+ signature = 'argv([{nr} [, {winid}]])',
+ },
+ asin = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Return the arc sine of {expr} measured in radians, as a |Float|
+ in the range of [-pi/2, pi/2].
+ {expr} must evaluate to a |Float| or a |Number| in the range
+ [-1, 1].
+ Returns NaN if {expr} is outside the range [-1, 1]. Returns
+ 0.0 if {expr} is not a |Float| or a |Number|.
+ Examples: >vim
+ echo asin(0.8)
+ < 0.927295 >vim
+ echo asin(-0.5)
+ < -0.523599
+
+ ]=],
+ float_func = 'asin',
+ name = 'asin',
+ params = { { 'expr', 'any' } },
+ returns = 'number',
+ signature = 'asin({expr})',
+ },
+ assert_beeps = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ 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|.
+
+ ]=],
+ name = 'assert_beeps',
+ params = { { 'cmd', 'any' } },
+ returns = '0|1',
+ signature = 'assert_beeps({cmd})',
+ },
+ assert_equal = {
+ args = { 2, 3 },
+ base = 2,
+ desc = [=[
+ 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: >vim
+ assert_equal('foo', 'bar')
+ <Will result in a string to be added to |v:errors|:
+ test.vim line 12: Expected 'foo' but got 'bar' ~
+
+ ]=],
+ name = 'assert_equal',
+ params = { { 'expected', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_equal({expected}, {actual} [, {msg}])',
+ },
+ assert_equalfile = {
+ args = { 2, 3 },
+ base = 1,
+ desc = [=[
+ 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.
+
+ ]=],
+ name = 'assert_equalfile',
+ params = {},
+ returns = '0|1',
+ signature = 'assert_equalfile({fname-one}, {fname-two})',
+ },
+ assert_exception = {
+ args = { 1, 2 },
+ desc = [=[
+ 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: >vim
+ try
+ commandthatfails
+ call assert_false(1, 'command should have failed')
+ catch
+ call assert_exception('E492:')
+ endtry
+ <
+ ]=],
+ name = 'assert_exception',
+ params = { { 'error', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_exception({error} [, {msg}])',
+ },
+ assert_fails = {
+ args = { 1, 5 },
+ base = 1,
+ desc = [=[
+ 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:". >vim
+ 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: >vim
+ assert_fails('cmd', ['E987:.*expected bool'])
+ <The second pattern, if present, is matched against the last
+ reported error. To only match the last error use an empty
+ string for the first error: >vim
+ 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.
+
+ ]=],
+ name = 'assert_fails',
+ params = {
+ { 'cmd', 'any' },
+ { 'error', 'any' },
+ { 'msg', 'any' },
+ { 'lnum', 'integer' },
+ { 'context', 'any' },
+ },
+ returns = '0|1',
+ signature = 'assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]])',
+ },
+ assert_false = {
+ args = { 1, 2 },
+ base = 1,
+ desc = [=[
+ 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.
+
+ ]=],
+ name = 'assert_false',
+ params = { { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_false({actual} [, {msg}])',
+ },
+ assert_inrange = {
+ args = { 3, 4 },
+ base = 3,
+ desc = [=[
+ 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.
+ ]=],
+ name = 'assert_inrange',
+ params = { { 'lower', 'any' }, { 'upper', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_inrange({lower}, {upper}, {actual} [, {msg}])',
+ },
+ assert_match = {
+ args = { 2, 3 },
+ base = 2,
+ desc = [=[
+ 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 |expr-=~|: 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: >vim
+ 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' ~
+
+ ]=],
+ name = 'assert_match',
+ params = { { 'pattern', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_match({pattern}, {actual} [, {msg}])',
+ },
+ assert_nobeep = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Run {cmd} and add an error message to |v:errors| if it
+ produces a beep or visual bell.
+ Also see |assert_beeps()|.
+
+ ]=],
+ name = 'assert_nobeep',
+ params = { { 'cmd', 'any' } },
+ returns = '0|1',
+ signature = 'assert_nobeep({cmd})',
+ },
+ assert_notequal = {
+ args = { 2, 3 },
+ base = 2,
+ desc = [=[
+ The opposite of `assert_equal()`: add an error message to
+ |v:errors| when {expected} and {actual} are equal.
+ Also see |assert-return|.
+
+ ]=],
+ name = 'assert_notequal',
+ params = { { 'expected', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_notequal({expected}, {actual} [, {msg}])',
+ },
+ assert_notmatch = {
+ args = { 2, 3 },
+ base = 2,
+ desc = [=[
+ The opposite of `assert_match()`: add an error message to
+ |v:errors| when {pattern} matches {actual}.
+ Also see |assert-return|.
+
+ ]=],
+ name = 'assert_notmatch',
+ params = { { 'pattern', 'any' }, { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_notmatch({pattern}, {actual} [, {msg}])',
+ },
+ assert_report = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Report a test failure directly, using String {msg}.
+ Always returns one.
+
+ ]=],
+ name = 'assert_report',
+ params = { { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_report({msg})',
+ },
+ assert_true = {
+ args = { 1, 2 },
+ base = 1,
+ desc = [=[
+ 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 or |v:true|.
+ When {actual} is not a number or |v:true| the assert fails.
+ When {msg} is given it precedes the default message.
+
+ ]=],
+ name = 'assert_true',
+ params = { { 'actual', 'any' }, { 'msg', 'any' } },
+ returns = '0|1',
+ signature = 'assert_true({actual} [, {msg}])',
+ },
+ atan = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Return the principal value of the arc tangent of {expr}, in
+ the range [-pi/2, +pi/2] radians, as a |Float|.
+ {expr} must evaluate to a |Float| or a |Number|.
+ Returns 0.0 if {expr} is not a |Float| or a |Number|.
+ Examples: >vim
+ echo atan(100)
+ < 1.560797 >vim
+ echo atan(-4.01)
+ < -1.326405
+
+ ]=],
+ float_func = 'atan',
+ name = 'atan',
+ params = { { 'expr', 'any' } },
+ returns = 'number',
+ signature = 'atan({expr})',
+ },
+ atan2 = {
+ args = 2,
+ base = 1,
+ desc = [=[
+ Return the arc tangent of {expr1} / {expr2}, measured in
+ radians, as a |Float| in the range [-pi, pi].
+ {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
+ Returns 0.0 if {expr1} or {expr2} is not a |Float| or a
+ |Number|.
+ Examples: >vim
+ echo atan2(-1, 1)
+ < -0.785398 >vim
+ echo atan2(1, -1)
+ < 2.356194
+
+ ]=],
+ name = 'atan2',
+ params = { { 'expr1', 'any' }, { 'expr2', 'any' } },
+ returns = 'number',
+ signature = 'atan2({expr1}, {expr2})',
+ },
+ blob2list = {
+ args = 1,
+ base = 1,
+ desc = [=[
+ Return a List containing the number value of each byte in Blob
+ {blob}. Examples: >vim
+ blob2list(0z0102.0304) " returns [1, 2, 3, 4]
+ blob2list(0z) " returns []
+ <Returns an empty List on error. |list2blob()| does the
+ opposite.
+
+ ]=],
+ name = 'blob2list',
+ params = { { 'blob', 'any' } },
+ returns = 'any[]',
+ signature = 'blob2list({blob})',
+ },
+ browse = {
+ args = 4,
+ desc = [=[
+ Put up a file requester. This only works when "has("browse")"
+ returns |TRUE| (only in some GUI versions).
+ The input fields are:
+ {save} when |TRUE|, select file to w