__pairs and __ipairs metamethods have incorrect annotations

How are you using the lua-language-server?

Visual Studio Code Extension (sumneko.lua)

Which OS are you using?

Windows

What is the issue affecting?

Annotations

Expected Behaviour

lua-language-server should specify correct function signatures for __pairs and __ipairs.

lua-language-server should in particular say that the __ipairs iterator generator function has 3 return values.

Following the annotation hints for __ipairs should not result in runtime errors.

Given that generic for k, v in pairs(t) --or ipairs(t) for pairs and ipairs are equivilant to:

do
  local f, s, var = pairs(t) --or ipairs(t)
  while true do
    local k, v = f(s, var)
    if k == nil then break end
    var = k
    <block>
  end
end

I believe these are the required function signatures:

__pairs = 
GEN_FUN(ITERABLE)
	RETURNS
		ITER_FUN(ITERABLE,KEY)
			RETURNS 
				KEY
				VALUE
		ITERABLE
		KEY_BEFORE_FIRST
OR nil

__ipairs = 
GEN_FUN(ITERABLE_ARRAY)
	RETURNS 
		ITER_FUN(ITERABLE_ARRAY,INDEX)
			RETURNS 
				INDEX OR nil
				VALUE
		ITERABLE_ARRAY
		INDEX_BEFORE_FIRST
OR nil

which I believe should be:

---@field __pairs (fun(t):((fun(t,k):(any,any)),any,any))|nil
---@field __ipairs (fun(t):((fun(t,k):((integer|nil),any)),any,integer))|nil

Actual Behaviour

__pairs annotation specifies the iterator function as taking a third argument, for the value. Lua versions 5.2 and 5.4 do not pass a third argument to the iterator function.

---@field __pairs (fun(t):((fun(t,k,v):any,any),any,any))|nil

__ipairs annotation specifies the iterator function as taking a third argument, for the value. Lua version 5.2 does not pass a third argument to the iterator function.

__ipairs annotation specifies the generator function as returning only 2 results. Following the annotation hinting results in nil being implicitly passed as the third argument, instead of the correct index.

---@field __ipairs (fun(t):(fun(t,k,v):(integer|nil),any))|nil

Reproduction steps

t = setmetatable({1,2,3}, {
  __ipairs = function(t) local function iter(t, k) k = k + 1 local v = t[k]; if v then return k, v end; end; return iter, t, 0 end,
})

for k, v in ipairs(t) do
  print(v)
end

(field) __ipairs: function|nil
function (t: any)
  -> fun(t: any, k: any, v: any):integer|nil
  2. any
function __ipairs(t: any)
  -> function
  2. unknown
  3. integer

Annotations specify that at most 2 return value(s) are required, found 3 returned here instead.Lua Diagnostics.(redundant-return-value)

Removing the extra return value as the annotation suggests results in :

.\sample.lua:2: attempt to perform arithmetic on local 'k' (a nil value)
stack traceback:
        .\source.txt:2: in function 'for iterator'
        .\source.txt:5: in main chunk
        [C]: in ?

Additional Notes

The example __ipairs sample is essentially what AI generated sample code looks like, so it is likely how someone would use __ipairs.

Lua 5.2 allows iteration with __ipairs to start at any point; this is useful if __ipairs is used to support non-standard ipairs iteration, such as starting from a negative index or starting at some arbitrary positive index, controlled by altering the third return value from the generator function to be a non-zero value.

Some of the __ipairs choices in the suggested annotations I made aren't technically explicitly mandated, but I feel they are in the spirit of the intended functionality; nothing stops anyone violating the implicit assumption that the keys are sequential, have numeric indexes, or they will be traversed in a given order:

t = setmetatable({a=1,b=2,c=3}, {
  __ipairs = function(t) local function iter(t, k) return next(t,k) end; return iter, t, nil end,
})

for k, v in ipairs(t) do
  print(k, v)
end

I kept my suggested annotation for __ipairs in line with the normal behaviors of ipairs when there is no __ipairs metamethod.

Log File

No response

__pairs と __ipairs のアノテーション定義から始め、提供された Lua の再現コードを lua-language-server 環境で実行します。推論されたシグネチャを Lua 5.2 および 5.4 のイテレーション動作と比較します。アノテーションがジェネレーターの 3 つの戻り値を受け入れ、イテレーターの引数と戻り値を正しくモデル化し、示されている診断やランタイムエラーを生成しなくなれば完了です。