simpleclass.d.lua

---@meta simpleclass
---Types declare for simpleclass module

---@class simpleclass
local sc = {}

---@class class<o>
---@field __proto o
---@field __classname string

---@class object
---@class object.class : class<object>
---@operator call: object

---@class interface : string[]

---@class super<cls, obj>
---@field self obj
---@field __class cls
---@field [string] unknown


-----------------------------------------------------------------------------------------------------


---@class class<o>
local c

---Create a instance
---@generic o
---@return o
function c:new() end

---Check if the class extends the base class
---@param base class
---@return boolean
function c:isExtends(base) end

---Check if the class implements the interfaces
---@param ... interface
---@return boolean  ok
---@return integer? arg_index if not ok
function c:isImplements(...) end

---Convert the object to a string
---@return string
function c:toString() end


-----------------------------------------------------------------------------------------------------


---The base class of all classes
---@class object.class
local o = {__classname = "object"}

---@return object
function o:new() end

---Check if the class implements the interface  
---If not, it returns the name of a method missing implements
---@param iface interface
---@return boolean ok
---@return string? meth
function o:isImpl(iface) end

---Clone an object (table)
---@generic T:table
---@param obj T
---@param isDeep? boolean Default `true`
---@return T
function o.clone(obj, isDeep) end

---@param self object
---@return string
function o.__tostring(self) end

---@class object
---@field __class object.class
o.__proto = {}

---Get the class of the object
---@return class
function o.__proto:getClass() end

---Check if the object is an instance of the class or interface  
---@param cls class|interface|"table"
---@return boolean
function o.__proto:isInstance(cls) end

---Convert the object to a string
---@return string
function o.__proto:toString() end


---Clone the object
---@param isDeep? boolean Default `true`
---@return object
function o.__proto:clone(isDeep) end

o.__proto.is = rawequal


-----------------------------------------------------------------------------------------------------


---@alias _ClassDefiner<T> fun(tbl: table): T
---@class _ClassCreator<T>
---@field [string] fun(cc: _ClassCreator<T>, tbl: table): T
local cc = {}

---Single inheritance keyword
---@generic T
---@param basename? string
---@return _ClassCreator<T>|_ClassDefiner<T>
function cc:extends(basename) end

---Implements the interfaces
---@generic T
---@param ... interface
---@return _ClassCreator<T>|_ClassDefiner<T>
function cc:implements(...) end

cc.impl = cc.implements

---Define the class body
---@generic T
---@param tbl table
---@return T
function cc:def(tbl) end


-----------------------------------------------------------------------------------------------------


---@alias _InterfaceDefiner<T> fun(lst: string[]): T
---@class _InterfaceCreator<T>
local ic = {}

---Extend the interface with other interfaces
---@generic T
---@param ... interface
---@return _InterfaceCreator<T>
function ic:extends(...) end


-----------------------------------------------------------------------------------------------------


---Get the type of a value, considering classes as special types  
---eg: 
---```lua
---simpleclass.type(Eagle()) => Eagle
---simpleclass.type("Hello") => "string"
---```
---@generic o:object
---@param obj o
---@return class<o> cls
function sc.type(obj) end

---Equivalent to `type` function
---@param v any
---@return type type
function sc.type(v) end

---Define a new class  
---eg:
---```lua
---class "MyClass" : MyBase {
---    __init = function(self)
---        super():__init()
---    end
---}
---```
---or anonymous:
---```lua
---local cls = class {}
---```
---@generic T:string
---@param name? `T`.class
---@return _ClassCreator<T>|_ClassDefiner<T>
function sc.class(name) end

---@generic T:table
---@param body T
---@return T
function sc.class(body) end

---Define a new interface
---@generic I:string
---@param name I.`I`
---@return _InterfaceCreator<I>|_InterfaceDefiner<I>
function sc.interface(name) end

---@param body? string[]
---@return interface
function sc.interface(body) end

--[[To call superclass methods  
eg: `super(cls, self):__init()`  

> If `debug` is available, it can automatically get the context,  
> so you can omit parameters in an instance method.  
> eg: `super():__init()` ]]
---@generic cls:class, obj:object
---@param cls cls
---@param obj? obj
---@return super<cls, obj>
function sc.super(cls, obj) end

---Check if the object is an instance of the class or interface
---(also compatible with lua type)
---@param obj object
---@param cls class|interface|type
---@return boolean
function sc.isinstance(obj, cls) end

---Check if `type(v) == T`
---@param v any
---@param T type
---@return boolean
function sc.isinstance(v, T) end

sc.issubclass = c.isExtends
sc.object = o

---The environment of the classes and interfaces
---@type {object: object.class, [string]: class|interface}
sc._ENV = {object = o}

---@alias alias.target function
---@alias alias.origin table<string, alias.target>

---Create an alias or a partial function for a method.
------
---To create an alias, do like this:
---```lua
---class "Person" {
---    walk = function(self) end;
---    alias.move :walk();
---}
---print(Person().move == Person().walk) --> true
---```
------
---To create a partial function, pass some arguments to the alias:  
---```lua
---class "Calculator" {
---    add = function(a, b) return a + b end;
---    alias.add1 .add(1);
---}
---print(Calculator.add1(2)) --> 3
---```
---> A positional partial can also be created outside a class body:
---> ```lua
---> partial = alias(func, ...)
---> ```
------
---## 「:」vs「.」
---It’s simple:   
---If a method is expected to be called with “:”, then its alias must also use the “:” syntax;  
---conversely, if it’s expected to be called with “.”, then its alias should use the “.” syntax.
---@alias simpleclass.alias table<string, alias.origin>|fun(function, ...):function
---@type simpleclass.alias
sc.alias = {}

---@alias property function

---Declare a property in the class body.  
---> eg: `property.my_prop;`  
---Once declared, the property can bind getter and setter methods.  
---A getter method should be named as `['get.my_prop']`, while setter as `['set.my_prop']`.  
------
---Here is a basic usage:  
---```lua
---class "MyClass" {
---    property.six;
---    ['get.six'] = function(self) return 6 end;
---}
---print(MyClass().six) --> 6
---```
---@alias simpleclass.property table<string, property>
---@type  simpleclass.property
sc.property = {}


-----------------------------------------------------------------------------------------------------


---@alias simpleclass.I_FEATURE
---| "general"  Full interface feature.
---| "nocheck"  Skip interface checking. 
---| "lexical"  Only interface syntax. (for LS analysis)

---@alias simpleclass.FIELD
---| "class"
---| "super"
---| "alias"
---| "interface"
---| "type"
---| "object"
---| "property"
---| "isinstance"
---| "issubclass"

---Whether to register classes as global variables automatically.  
---Default true when import globally, false otherwise. Could be overridden in runtime.
---@type boolean
sc.AUTO_GLOBAL = false

---Interface feature to use, meaningless if interface module not included.  
---**Warning**: switch in "general" & "nocheck" is safe, BUT "lexical" skipping definition is irreversible.
---@type simpleclass.I_FEATURE
sc.I_FEATURE = "general"

---Import fields from simpleclass module to environment.  
---eg:
---```
---simpleclass.env_import({
---    "class",
---    "super",
---    ["type"] = "cls_type"
---}, _ENV)
---```
---which means:
---```python
---from simpleclass import
---    class,
---    super,
---    type as cls_type
---```
---@param fields {[simpleclass.FIELD]?: string, [integer]?: simpleclass.FIELD}
---@param env? table Default to `_G` if missing.
function sc.env_import(fields, env) end

class = sc.class
super = sc.super
interface = sc.interface
isinstance = sc.isinstance
issubclass = sc.issubclass

object = sc.object
property = sc.property


-----------------------------------------------------------------------------------------------------


return sc