How can I declare Interfaces (or Traits)?

[leiserfg]

I will like to mark a set of classes with the same methods but there is no parent class so it's not an inheritance. But it will be good for the API to make clear they are all of the same kind nonetheless.

[sumneko]

Please provide example codes.

[leiserfg]

For instance, I need to annotate a function receiving file-like objects:

local function fancy_print(string, file)
  file.write(string)
end

How do I annotate the fact that file is of a "kind" that has a write field of type fun(arg:string): nil but it actually does not need to belong to any known class (as duck-typing is a common pattern in lua).

[carsakiller]

The @class annotation behaves more like an interface really and isn't used just for classes.

Here is one option:

---@class File
---@field write fun(arg: string): nil

---Print fancily
---@param string string String to print
---@param file File The file to print to
local function fancy_print(string, file)
    file.write(string)
end

or:

---@class File
local File = {}

---Write to file
---@param arg string
---@return nil
function File.write(arg) end

---Print fancily
---@param string string String to print
---@param file File The file to print to
local function fancy_print(string, file)
    file.write(string)
end

Or if you don't want to use @class:

---Print fancily
---@param string string String to print
---@param file { write: fun(arg: string): nil } The file to print to
local function fancy_print(string, file)
	file.write(string)
end

[itaranto]

@carsakiller I don't think this actually works, let me give you a real example:

I have the Renderer interface, which means, any table that implements the render method (or has the render function). As far as I know I can declare that like this:

-- A PlantUML renderer.
---@class plantuml.Renderer
---@field render fun(file: string): nil

The problem is when I want to create multiple implementations for this "interface" that I want to return them as plantuml.Renderer. For example:

---@param renderer_config table
---@return plantuml.Renderer?
local function create_renderer(renderer_config)
  local type = renderer_config.type
  local options = renderer_config.options

  local renderer
  if type == 'text' then
    renderer = text.Renderer:new(options)
  elseif type == 'image' then
    renderer = image.Renderer:new(options)
  elseif type == 'imv' then
    renderer = imv.Renderer:new(options)
  else
    print(string.format('[plantuml.nvim] Invalid renderer type "%s"', type))
  end

  return renderer
end

In the previous snippet, each of text.Renderer:new, image.Renderer:new and imv.Renderer:new returns a different table that I want to view as the "interface" plantuml.Renderer but the LS returns the following error:

Diagnostics:
Annotations specify that return value #1 has a type of `(plantuml.Renderer)?`, returning value of type `image.Renderer|imv.Renderer|text.Renderer` here instead.
- `text.Renderer` cannot match `(plantuml.Renderer)?`
- Type `text.Renderer` cannot match `nil`
- Type `text.Renderer` cannot match `plantuml.Renderer` [return-type-mismatch]

But if then I modify the return type of create_renderer to be image.Renderer|imv.Renderer|text.Renderer then I cannot use this returned value in other functions that take a plantuml.Renderer as a parameter. In such case the error I get is:

Diagnostics:
Cannot assign `image.Renderer|imv.Renderer|text.Renderer` to parameter `plantuml.Renderer`.
- `text.Renderer` cannot match `plantuml.Renderer`
- Type `text.Renderer` cannot match `plantuml.Renderer` [param-type-mismatch]

Is there a way to decalre "interfaces" of some sort with LuaCATS?

[itaranto]

I solved this problem by using @alias not @class, like this:

-- A PlantUML renderer.
---@alias plantuml.Renderer { render: fun(file: string): nil }

But I think this is a little but cumbersome, specially when the number of method is larger.

Is there any way to make this work with @class?

[jpeletier]

@carsakiller I tried your example, but it does not work:

---Print fancily
---@param string string String to print
---@param file { write: fun(arg: string): nil } The file to print to
local function fancy_print(string, file)
	file.write(string)
end

a = { x = 123 }

fancy_print("test.txt", a);  --- <- should give an error, but accepts any table. 'a' does not have a write() method
fancy_print("test.txt", {});  --- <- should give an error, but the parameter is accepted

fancy_print("test.txt", 66);  --- OK: shows an error "cannot assign iteger to parameter... " 

So my problem is that any table or class instance is accepted when calling fancy_print(), when it should reject objects that do not satisfy the interface.

Using a @class as an interface does not work either, for example:

---@class File
---@field write fun(arg: string): nil

---@class OtherFile
---@field write fun(arg: string): nil

---Print fancily
---@param string string String to print
---@param file File The file to print to
local function fancy_print(string, file)
    file.write(string)
end


---@type File
local f = {}

---@type OtherFile
local off = {}

fancy_print("test.txt", f) --- works
fancy_print("test.txt", of) --- does not work

The error is:

Cannot assign `OtherFile` to parameter `File`.
- `OtherFile` cannot match `File`
- Type `OtherFile` cannot match `File`Lua Diagnostics.(param-type-mismatch)

So I am out of options to use something like interfaces. Is there any other workaround or LS settings I need to tweak?

Thank you

[carsakiller]

@jpeletier, things can be improved slightly using the below. Classes aren't really interfaces, but they can be hacked around to make them act a little like interfaces if you use @type.

---@class Writer
---@field write fun(arg: string): nil

---@class OtherWriter : Writer
---@field write fun(arg: string): nil

---Print fancily
---@param string string String to print
---@param file Writer The file to print to
local function fancy_print(string, file) end

---@type Writer
local a = { x = 123 } --- This is asserted as missing `write`

fancy_print("test.txt", a);  --- This still isn't asserted :(
fancy_print("test.txt", {});  --- Err: missing `write`
fancy_print("test.txt", 66);  --- Err: integer is not `Writer`

---@type OtherWriter
local b = {}

fancy_print("test.txt", b) --- This will error if `OtherWriter` doesn't inherit from `Writer`
fancy_print("test.txt", {}) --- Err: missing `write`
fancy_print("test.txt", 66) --- Err: integer is not `Writer`

Using inheritance can allow our OtherWriter to be accepted as a Writer

[jpeletier]

@carsakiller Thank you for your fast response. I tried with these tweaks, but I could not find a way for my use case, other than directly inheriting, which is not ideal.

Perhaps an ---@interface tag would help solve the issue? @interface would have the same syntax as @class

Another option could be to have @class support multiple inheritance, but that is not something that makes sense in the underlying Lua I think.

In any case, thank you very much.