How do you describe __add, __sub, etc. metamethods?

[filloax]

Example:

---@class Vector
---@field X number
---@field Y number
---@type fun(x: number, y: number): Vector
local Vector = {}

---@param right Vector
function Vector:__add(right)
    return Vector(self.X + right.X, self.Y + right.Y)
end

setmetatable(Vector, {
    ---@param self Vector
    ---@param right Vector
    __add = function(self, right)
        return self:Add(right)
    end
})

local a = Vector(1, 2)
local b = Vector(3, 4)
local c = a + b -- c is 'any'

I'd like to make c be detected as Vector somehow, is it possible?

[filloax]

For some reason cannot edit but inside of __add was meant to be a call to self:__add, not self:Add

[mkster]

I would like to know if this is possible too @sumneko

[flrgh]

Wall of text with some of my ideas:

I believe this could be implemented in a generic sense without adding metamethod support.

For any expression result = left {{operator}} right where left/right are of a known class, the type of result is inferred from the type of left or right. If they're the same type, then result has that type. If they are of differing types, consult operator precedence logic to determine if result has the same type of left or right.

IMO this should be config option that is turned on by default, as it would satisfy most use cases without requiring developers to write any additional annotations:

---@class Foo

---@type Foo
local a, b

local c = a + b -- `c` is of type `Foo`

Support for more elaborate metamethod annotations could be added later on to do things like...

explicit return type

---@class Foo
local Foo = {
  ---@return Bar
  __add = function(self, other)
    return -- ...
  end,
}

---@class Bar : Foo

---@type Foo
local a, b

local c = a + b -- `c` is of type `Bar`

If parsing and discovering metamethods is too tricky/expensive to do in the language server, an explicit annotation could be created:

---@class Foo
local Foo = {
  ---@operator:add Foo 
  ---@return Bar
  __add = function(self, other)
    return -- ...
  end,
}

Alternatively, maybe some kind of @metatable annotation would cut down on expensive tracing and make types more flexible:

---@class Point
---@field x integer
---@field y integer

---@metatable Point
local point_mt = {
  ---@return Point
  __add = function(self, other)
    local new = {
      x = self.x + other.x,
      y = self.y + other.y
    }
    return setmetatable(new, point_mt)
  end,
}

unsupported operator error-checking

If desired, operator type inference could be turned off at a global level via config option, which then forces developers to explicitly define operator handlers for their classes:

---@class Foo
local Foo = {}

---@type Foo
local a, b

local c = a + b -- "warn: type `Foo` does not support `+` operator"

operator type checking

By annotating params for operator metamethods, type-checking can be done:

---@class Foo
local Foo = {
  ---@param self Foo|Bar
  ---@param other Foo|Bar
  ---@return Bar
  __add = function(self, other)
    return -- ...
  end,
}

---@class Bar : Foo

---@class Baz

---@type Foo
local a, b

local c = a + b -- `c` is of type `Bar`

---@type Baz
local d

local e = a + d -- "warn: type `Foo` and type `Baz` cannot be added"

[carsakiller]

There is now an issue open for documenting metamethods: #1188

[C3pa]

You can now document operator metamethods. See the Wiki.