mark functions with a magic type

Author: tapple

generated/secondlife.d.luau

@@ -230,7 +230,7 @@ export type PrimParamsSetterType = typeof(
 )
 
 
-declare function assert<T>(value: T?, message: string?): T
+declare function assert<T>(value: T?, message: string?): T -- magic type
 declare function dangerouslyexecuterequiredmodule(f: (...any) -> ...any): ...any
 declare function error(obj: any, level: number?): never
 declare function gcinfo(): number
@@ -247,10 +247,10 @@ declare function rawequal(a: any, b: any): boolean
 declare function rawget<K, V>(t: {[K]: V}, k: K): V?
 declare function rawlen<K, V>(t: {[K]: V} | string): number
 declare function rawset<K, V>(t: {[K]: V}, k: K, v: V): {[K]: V}
-declare function require(target: string): any
-declare function select(i: string | number, ...any): any
+declare function require(target: string): any -- magic type
+declare function select(i: string | number, ...any): any -- magic type
 declare setfenv: nil
-declare function setmetatable(t: { [any]: any }, mt: { [any]: any }?): ()
+declare function setmetatable(t: { [any]: any }, mt: { [any]: any }?): () -- magic type
 declare function tonumber(s: string, base: number?): number?
 declare function toquaternion(val: string? | quaternion): quaternion?
 declare function torotation(val: string? | quaternion): quaternion?
@@ -474,14 +474,14 @@ declare quaternion: ((x: number, y: number, z: number, s: number) -> quaternion)
 declare string: {
   byte: (s: string, i: number?, j: number?) -> ...number,
   char: (...number) -> string,
-  find: (s: string, pattern: string, init: number?, plain: boolean?) -> (number?, number?, ...string),
-  format: (formatstring: string, ...any) -> string,
-  gmatch: (s: string, pattern: string) -> () -> ...string,
+  find: (s: string, pattern: string, init: number?, plain: boolean?) -> (number?, number?, ...string), -- magic type
+  format: (formatstring: string, ...any) -> string, -- magic type
+  gmatch: (s: string, pattern: string) -> () -> ...string, -- magic type
   gsub: (s: string, pattern: string, repl: string | { [string]: string } | (...string) -> string, maxn: number?) -> (string, number),
   len: (s: string) -> number,
   lower: (s: string) -> string,
-  match: (s: string, pattern: string, init: number?) -> ...string,
-  pack: (fmt: string, ...any) -> string,
+  match: (s: string, pattern: string, init: number?) -> ...string, -- magic type
+  pack: (fmt: string, ...any) -> string, -- magic type
   packsize: (fmt: string) -> number,
   rep: (s: string, n: number) -> string,
   reverse: (s: string) -> string,
@@ -515,9 +515,9 @@ declare table: {
   find: <V>(t: {V}, v: V, i: number?) -> number?,
   clear: (t: {}) -> (),
   shrink: <V>(t: {V}, shrink_sparse: boolean?) -> {V},
-  freeze: <table>(t: table) -> table,
+  freeze: <table>(t: table) -> table, -- magic type
   isfrozen: (t: {}) -> boolean,
-  clone: <table>(t: table) -> table,
+  clone: <table>(t: table) -> table, -- magic type
 }
 
 

lsl_definitions/slua.py

@@ -111,6 +111,8 @@ class SLuaFunction(SLuaFunctionBase):
     must_use: bool = False
     """Emit a warning if the return value is not used.
     See https://kampfkarren.github.io/selene/usage/std.html#must_use."""
+    magic_type: bool = False
+    """The typechecker has custom logic for this function."""
     overloads: List[SLuaFunctionOverload] = dataclasses.field(default_factory=list)
 
     @property
@@ -160,7 +162,10 @@ def write_luau_global_def(self, f: TextIO, indent: int = 0) -> None:
             f.write(f"function {self.name}")
             f.write(self.type_parameters_string)
             f.write(self.parameters_string)
-            f.write(f": {self.return_type}\n")
+            f.write(f": {self.return_type}")
+            if self.magic_type:
+                f.write(" -- magic type")
+            f.write("\n")
 
     def write_luau_table_def(self, f: TextIO, indent: int = 0, suffix=",") -> None:
         """For declaring functions within a table/module"""
@@ -176,6 +181,8 @@ def write_luau_table_def(self, f: TextIO, indent: int = 0, suffix=",") -> None:
                 f.write(overload.type_def_string)
             f.write(")")
         f.write(suffix)
+        if self.magic_type:
+            f.write(" -- magic type")
         f.write("\n")
 
 
@@ -762,6 +769,7 @@ def _validate_function(
                 local_only=data.get("local-only", False),
                 slua_removed=data.get("slua-removed", False),
                 must_use=data.get("must-use", False),
+                magic_type=data.get("magic-type", False),
             )
             self._validate_identifier(func.name)
             self._validate_scope(func.name, scope)

slua_definitions.schema.json

@@ -187,6 +187,11 @@
                     "description": "See https://github.com/secondlife/slua/blob/main/Common/include/Luau/Bytecode.h#L542",
                     "type": "boolean"
                 },
+                "magic-type": {
+                    "const": true,
+                    "markdownDescription": "The typechecker has custom logic for this function. Look for attachMagicFunction in the source code.",
+                    "type": "boolean"
+                },
                 "comment": {
                     "markdownDescription": "A brief description of this function.",
                     "type": "string"

slua_definitions.yaml

@@ -359,6 +359,7 @@ functions:
     type: string?
   return-type: T
   fastcall: true
+  magic-type: true
 - name: collectgarbage
   comment: Run the garbage collector
   parameters:
@@ -538,6 +539,7 @@ functions:
     comment: The name of the external module.
     type: string
   return-type: any
+  magic-type: true
 - name: select
   comment: Returns a subset of arguments or the number of arguments.
   parameters:
@@ -549,6 +551,7 @@ functions:
     type: ...any
   return-type: any
   fastcall: true
+  magic-type: true
 - name: setfenv
   comment: Set the scoped environment for the given function.
   parameters:
@@ -569,6 +572,7 @@ functions:
     type: "{ [any]: any }?"
   return-type: ()
   fastcall: true
+  magic-type: true
 - name: tonumber
   comment: Converts the input string to a number in the specified base.
   parameters:
@@ -2048,6 +2052,7 @@ modules:
       type: boolean?
     return-type: (number?, number?, ...string)
     must-use: true
+    magic-type: true
   - name: format
     comment: Formats input values into a string using printf-style format specifiers.
     parameters:
@@ -2060,6 +2065,7 @@ modules:
       optional: false
     return-type: string
     must-use: true
+    magic-type: true
   - name: gmatch
     comment: Returns an iterator function for pattern matches
     parameters:
@@ -2071,6 +2077,7 @@ modules:
       type: string
     return-type: () -> ...string
     must-use: true
+    magic-type: true
   - name: gsub
     comment: Performs pattern-based substitution in a string.
     parameters:
@@ -2119,6 +2126,7 @@ modules:
       type: number?
     return-type: '...string'
     must-use: true
+    magic-type: true
   - name: pack
     comment: Packs values into a binary string.
     parameters:
@@ -2130,6 +2138,7 @@ modules:
       type: ...any
     return-type: string
     must-use: true
+    magic-type: true
   - name: packsize
     comment: Returns the size of a packed string for the given format.
     parameters:
@@ -2449,6 +2458,7 @@ modules:
       type: table # should be: generic table. See #56
       selene-type: table
     return-type: table
+    magic-type: true
   - name: isfrozen
     comment: Returns true if a table is frozen.
     parameters:
@@ -2467,6 +2477,7 @@ modules:
       selene-type: table
     return-type: table
     must-use: true
+    magic-type: true
 - name: utf8
   comment: UTF-8 support library.
   functions: