init.lua

---Öbject - Base superclass that implements ÖØP.
---
---Key features of this library:
---
---+ metamethods inheritance;
---+ store all metadata in metatables (no `__junk` in actual tables);
---+ can subtly identify class membership;
---+ tiny and fast, readable source.
---@class lib.object
local Object = {
  classname = "lib.object",
  super = {},
}

---Adds all metamethods from self and all parents to the specified table.
---Maintains the order of the hierarchy: Rect > Point > Object.
---@param self lib.object Apply from.
---@param apply_here table Apply to.
local function apply_meta_from_parents(self, apply_here)
  for key, value in self:iter() do
    if apply_here[key] == nil and string.find(key, "__") == 1 then
      apply_here[key] = value
    end
  end
end

---Adds `__index` metamethods from self or closest parent to the table.
---@param self lib.object Apply from.
---@param apply_here table Apply to.
local function apply_closest_meta_index(self, apply_here)
  local i = self.__index
  if i == nil then
    apply_here.__index = self
    return
  end
  apply_here.__index = function(instance, key)
    local t = type(i)
    local v
    if t == "function" then
      v = i(instance, key)
    elseif t == "table" then
      v = i[key]
    else
      error("\"__index\" must be a function or table", 2)
    end
    if v ~= nil then
      return v
    end
    if key == "new" or key == "extend" then
      error("attempt to use instance as class", 2)
    end
    return self[key]
  end
end

---Creates **uninitialized** instance of the class.
---
---After calling this method you have to initialize the instance:
---```lua
---local rect = Rectangle:new():init(2, 4, 6, 8)
---```
---Why I can't mix `new()` with `init()`? - I can, and this is just a single
---line of code, but in this case you will not see hints from LSP :(
---
---But if you want short syntax anyway - you can just call class as function:
---```lua
---local rect = Rectangle(2, 4, 6, 8)
---```
---@generic T
---@param self T
---@return T
function Object:new()
  local obj_mt = {
    __index = self,
    __tostring = function()
      return "instance of " .. self.classname
    end,
  }
  local obj = setmetatable({}, obj_mt)
  apply_meta_from_parents(self, obj_mt)
  apply_closest_meta_index(self, obj_mt)
  return obj
end

---Initializes the class.
---
---By default an object takes a table with fields and applies them to itself.
---You can (and probably should) replace this method with your own in subclass.
---@param fields? table New fields.
function Object:init(fields)
  local t = type(fields)
  if t ~= "table" then
    error("\"Object:init()\" expected a table, but got " .. t, 3)
  end
  for key, value in pairs(fields) do
    self[key] = value
  end
end

---Creates a new class by inheritance.
---@generic T
---@param self T
---@param name string New class name.
---@vararg table|lib.object? Additional properties.
---@return T
function Object:extend(name, ...)
  if type(name) ~= "string" then
    error("class must have a name", 2)
  end

  local cls, cls_mt = {}, {}
  for key, value in pairs(getmetatable(self)) do
    cls_mt[key] = value
  end
  for _, extra in ipairs({ ... }) do
    for key, value in pairs(extra) do
      cls[key] = value
    end
  end

  cls.classname = name
  cls.super = self
  cls_mt.__index = self
  cls_mt.__tostring = function()
    return "class " .. name
  end
  return setmetatable(cls, cls_mt)
end

---Returns the "membership range" between self and the checking class.
---Returns `0` if belongs to it or `false` if there is no membership.
---Positive number means number of subclasses between `self` and `Test`.
---@param Test string|lib.object Test class.
---@param limit? integer Check depth (default unlimited).
---@return integer|boolean
function Object:has(Test, limit)
  local t = type(Test)
  local searchedname
  if t == "string" then
    searchedname = Test
  else
    if t ~= "table" then
      return false
    end
    searchedname = Test.classname
  end

  local i = 0
  while self.super do
    if self.classname == searchedname then
      return i
    end
    if i == limit then
      return false
    end
    self = self.super
    i = i + 1
  end
  return false
end

---Identifies affiliation to class.
---@param Test string|lib.object
---@return boolean
function Object:is(Test)
  return self:has(Test, 0) == 0
end

---Loop iterator.
---Goes through all fields and methods (including extended)
---except those belonging to Object itself.
---@generic T, K, V
---@param self T<K, V>
---@param key? K
---@return fun(): K, V, T
function Object:iter(key)
  local value
  local returned = {}
  local function next_iter()
    key, value = next(self, key)
    if key ~= nil then
      if returned[key] then
        return next_iter()
      else
        returned[key] = true
        return key, value, self
      end
    else
      if self ~= Object then
        self = self.super
        return next_iter()
      end
    end
  end
  return next_iter
end

return setmetatable(Object, {
  __tostring = function(self)
    return "class " .. self.classname
  end,
  __call = function(self, ...)
    return self:new():init(...)
  end,
})