Function annotation to require a parameter to have a certain metamethod implemented

[Rathoz]

Hypothetically, say we have this function:

function Operator.add(a, b)
	return a + b
end

The naive case the annotation would be

---@param a number
---@param b number
---@return number

However the metamethod __add also exists, which gives support to + operator.
Hence more accurate annotation would be

---@generic V [[TODO something to limit to only implementations with `__add`]]
---@param a V
---@param b V
---@return V

Now this annotation is not fully correct neither (but tbh good enough for me).

In fully correct annotation only param a needs the metamethod implemented, param b needs to be valid input to a.__add (via ---@operator add(...):... and the return value should be the return value of said operator annotation.

Is it possible to limit the annotation to anything with an implemented metamethod?

[C3pa]

What is the reason for that? Builtin number type has __add metamethod.

[Rathoz]

Sorry for late reply. And also sorry for wall of text...

So we have a heavily functional oriented setup.

So say I want to sum all the values in an Array; I would just do

Array.reduce(arr, Operator.add)

These are the annotations for the respective functions

---@generic T, V
---@param array T[]
---@param operator fun(aggregate: V, arrayValue: T): V
---@param initialValue V?
---@return V?
function Array.reduce(array, operator, initialValue)
-- stuff
end

---@param a number
---@param b number
---@return number
function Operator.add(a, b)
	return a + b
end

And this works great for the above use-case of summarizing all numbers in an array.

However the Operator.add() can do much more than summing numbers.

It will work with anything that has implemented the __add metamethod. For instance say I have a Set class

---@class Set
local Set = ...
-- boilerplate

function Set:_add(value)
	self.data[value] = true
end

function Set:add(value)
	if Set._isSet(value) then
		for val in pairs(value) do
			self:_add(val)
		end
	else
		self:_add(value)
	end

	return self
end

function Set:_addImmutable(value)
	return self:copy():add(value)
end

Set.__add = Set._addImmutable

Now I would be able to

local sets = {
  Set{5, 4, 3},
  Set{3, 6. 2},
  Set{1, 6, 100},
}

sets[1]+ sets[2] -- Set{2, 3, 4, 5, 6}
sets[3]+ 5 + 6 -- Set{1, 5, 6, 100}

Array.reduce(sets, Operator.add) -- Set{1, 2, 3, 4, 5, 6, 100}

local myNewCoolSet = Set{5, 3, 6}
local numbers = {5, 7, 3, 7, 1, 9}
Array.reduce(numbers, Operator.add, myNewCoolSet) -- Set{1, 3, 5, 6, 7, 9}

However this will give annotation warning, as Operator.add is set up to only allow for ---@param number input. However giving it ---@param any would not be helpful, as plenty of incorrect inputs

[sumneko]

You have to annotate metamethods separately for each type, which mimics Lua's metatable behavior.

(Translated by ChatGPT)