From debde573b47530b94fe8572fd05ba3f067afa438 Mon Sep 17 00:00:00 2001 From: "efve.zff" Date: Sat, 28 Feb 2026 17:56:48 +0800 Subject: [PATCH 1/3] fix: std functions should match official manuals --- .../resources/std/coroutine.lua | 12 +++- .../resources/std/debug.lua | 60 ++++++++++++------- .../resources/std/global.lua | 8 ++- .../resources/std/math.lua | 22 ++++++- .../resources/std/os.lua | 6 +- .../resources/std/string.lua | 13 +++- .../resources/std/table.lua | 4 +- .../resources/std/utf8.lua | 26 +++++++- 8 files changed, 113 insertions(+), 38 deletions(-) diff --git a/crates/emmylua_code_analysis/resources/std/coroutine.lua b/crates/emmylua_code_analysis/resources/std/coroutine.lua index 75f169139..c84c2b465 100644 --- a/crates/emmylua_code_analysis/resources/std/coroutine.lua +++ b/crates/emmylua_code_analysis/resources/std/coroutine.lua @@ -32,7 +32,7 @@ function coroutine.create(f) end ---@param co? thread ---@return boolean ---@nodiscard -function coroutine.isyieldable() end +function coroutine.isyieldable(co) end ---@version > 5.4 --- @@ -61,10 +61,18 @@ function coroutine.close(co) end ---@return any ... function coroutine.resume(co, val1, ...) end +---@version 5.1 +--- +--- Returns the running coroutine, or nil when called by the main thread. +---@return thread? +---@nodiscard +function coroutine.running() end + +---@version > 5.2 --- --- Returns the running coroutine plus a boolean, true when the running --- coroutine is the main one. ----@return thread, string +---@return thread, boolean ---@nodiscard function coroutine.running() end diff --git a/crates/emmylua_code_analysis/resources/std/debug.lua b/crates/emmylua_code_analysis/resources/std/debug.lua index 477a1df32..9514304de 100644 --- a/crates/emmylua_code_analysis/resources/std/debug.lua +++ b/crates/emmylua_code_analysis/resources/std/debug.lua @@ -40,9 +40,11 @@ function debug.getfenv(o) end --- Returns the current hook settings of the thread, as three values: the --- current hook function, the current hook mask, and the current hook count --- (as set by the `debug.sethook` function). ----@overload fun():thread +---@overload fun():function?, string, integer ---@param thread thread ----@return thread +---@return function? hook +---@return string mask +---@return integer count function debug.gethook(thread) end ---@class debuglib.DebugInfo @@ -65,7 +67,7 @@ function debug.gethook(thread) end ---@alias debuglib.InfoWhat ---|+"n" # `name`, `namewhat` ----|+"S" # `source`, `short_src`, `linedefined`, `lalinedefined`, `what` +---|+"S" # `source`, `short_src`, `linedefined`, `lastlinedefined`, `what` ---|+"l" # `currentline` ---|+"t" # `istailcall` ---|+"u" # `nups`, `nparams`, `isvararg` @@ -177,8 +179,8 @@ function debug.getregistry() end --- no known names (variables from chunks saved without debug information). ---@param f function ---@param up integer ----@return string name ----@return any value +---@return string? name +---@return any? value ---@nodiscard function debug.getupvalue(f, up) end @@ -254,12 +256,12 @@ function debug.sethook(thread, hook, mask, count) end --- raises an error when called with a `level` out of range. (You can call --- `getinfo` to check whether the level is valid.) Otherwise, it returns the --- name of the local variable. ----@overload fun(level:integer, var:string, value:any):string +---@overload fun(level:integer, var:string, value:any):string? ---@param thread thread ---@param level integer ---@param var string ---@param value any ----@return string +---@return string? function debug.setlocal(thread, level, var, value) end --- @@ -279,7 +281,7 @@ function debug.setmetatable(value, meta) end ---@param f fun():any ---@param up integer ---@param value any ----@return string +---@return string? function debug.setupvalue(f, up, value) end --- Sets the given `value` as the `n`-th associated to the given `udata`. @@ -289,22 +291,40 @@ function debug.setupvalue(f, up, value) end ---@param udata userdata ---@param value any ---@param n integer ----@return userdata +---@return userdata? function debug.setuservalue(udata, value, n) end ---- Generates a traceback of the call stack. ---- When called with no arguments, returns a traceback of the current thread. ---- When the first argument is a thread, the traceback is generated for that thread; ---- the optional second argument (if a string) is prepended to the traceback, and the ---- optional third argument sets the level where the traceback should start (default is 1). ---- When the first argument is not a thread and not nil, it is treated as an optional message. ---- In that case, the traceback is generated for the current thread and the second argument, ---- if provided, specifies the starting level. +---@version 5.1 +--- +--- Returns a string with a traceback of the call stack. An optional message +--- string is appended at the beginning of the traceback. An optional level +--- number tells at which level to start the traceback (default is 1, the +--- function calling traceback). +---@overload fun(): string +---@overload fun(message?: string, level?: integer): string +---@param thread? thread +---@param message? string +---@param level? integer +---@return string +function debug.traceback(thread, message, level) end + +---@version > 5.2 +--- +--- If message is present but is neither a string nor nil, this function +--- returns message without further processing. Otherwise, it returns a string +--- with a traceback of the call stack. The optional message string is appended +--- at the beginning of the traceback. An optional level number tells at which +--- level to start the traceback (default is 1, the function calling traceback). +---@generic T ---@overload fun(): string ---@overload fun(message?: string, level?: integer): string ----@param thread? thread|integer Optional thread or nil. If not a thread, it is interpreted as the message. ----@param message? string Optional message to prepend to the traceback. If not a string (or nil), it is returned as is. ----@param level? integer Optional level from which to start the traceback (default is 1). +---@overload fun(message: T, level?: integer): T +---@overload fun(thread: thread): string +---@overload fun(thread: thread, message?: string, level?: integer): string +---@overload fun(thread: thread, message: T, level?: integer): T +---@param thread? thread +---@param message? string|T +---@param level? integer ---@return string function debug.traceback(thread, message, level) end diff --git a/crates/emmylua_code_analysis/resources/std/global.lua b/crates/emmylua_code_analysis/resources/std/global.lua index e39c508e8..fcf00a75a 100644 --- a/crates/emmylua_code_analysis/resources/std/global.lua +++ b/crates/emmylua_code_analysis/resources/std/global.lua @@ -84,7 +84,7 @@ function collectgarbage(opt, ...) end --- `dofile` propagates the error to its caller (that is, `dofile` does not run --- in protected mode). ---@param filename? string ----@return table +---@return any ... function dofile(filename) end --- @@ -299,6 +299,7 @@ function rawlen(v) end ---@param table table ---@param index any ---@param value any +---@return table function rawset(table, index, value) end --- @@ -469,8 +470,9 @@ function unpack(list, i, j) end ---@version > 5.4 --- ----@param message string -function warn(message) end +---@param msg1 string +---@param ... string +function warn(msg1, ...) end ---@type string[] arg = {} diff --git a/crates/emmylua_code_analysis/resources/std/math.lua b/crates/emmylua_code_analysis/resources/std/math.lua index bd1f15464..420f014a7 100644 --- a/crates/emmylua_code_analysis/resources/std/math.lua +++ b/crates/emmylua_code_analysis/resources/std/math.lua @@ -17,7 +17,7 @@ math = {} --- ---- Returns the absolute value of `x`. (integer/float) +--- Returns the maximum value between `x` and `-x`. (integer/float) ---@overload fun(x:integer):integer ---@param x number ---@return number @@ -160,12 +160,30 @@ function math.rad(x) end ---@return integer function math.random(m, n) end +---@version 5.1, 5.2, 5.3 --- --- Sets `x` as the "seed" for the pseudo-random generator: equal seeds --- produce equal sequences of numbers. ---@param x integer function math.randomseed(x) end +---@version > 5.3 +--- +--- When called with at least one argument, the integer parameters `x` and `y` +--- are joined into a 128-bit seed that is used to reinitialize the pseudo-random +--- generator; equal seeds produce equal sequences of numbers. The default for +--- `y` is zero. +--- +--- When called with no arguments, Lua generates a seed with a weak attempt +--- for randomness. +--- +--- This function returns the two seed components that were effectively used, +--- so that setting them again repeats the sequence. +---@param x? integer +---@param y? integer +---@return integer, integer +function math.randomseed(x, y) end + --- --- Returns the sine of `x` (assumed to be in radians). ---@param x number @@ -198,7 +216,7 @@ function math.tointeger(x) end --- Returns "`integer`" if `x` is an integer, "`float`" if it is a float, or --- **nil** if `x` is not a number. ---@param x any ----@return 'integer'|'float'|'nil' +---@return 'integer'|'float'|nil function math.type(x) end ---@version >5.3 diff --git a/crates/emmylua_code_analysis/resources/std/os.lua b/crates/emmylua_code_analysis/resources/std/os.lua index bf2856f89..a86b32a10 100644 --- a/crates/emmylua_code_analysis/resources/std/os.lua +++ b/crates/emmylua_code_analysis/resources/std/os.lua @@ -132,17 +132,15 @@ function os.execute(command) end --- --- If the optional second argument `close` is true, closes the Lua state before --- exiting. ----@param code integer +---@param code? boolean|integer ---@param close? boolean ----@return integer function os.exit(code, close) end ---@version 5.1 --- --- Calls the C function exit, with an optional `code`, to terminate the host --- program. The default value for `code` is the success code. ----@param code integer ----@return integer +---@param code? integer function os.exit(code) end --- diff --git a/crates/emmylua_code_analysis/resources/std/string.lua b/crates/emmylua_code_analysis/resources/std/string.lua index 47fe6a0a2..44125a35e 100644 --- a/crates/emmylua_code_analysis/resources/std/string.lua +++ b/crates/emmylua_code_analysis/resources/std/string.lua @@ -147,6 +147,13 @@ function string.format(fmt, ...) end ---@return fun():string?... function string.gmatch(s, pattern) end +---@version > 5.4 +---@param s string +---@param pattern string +---@param init? integer +---@return fun():string?... +function string.gmatch(s, pattern, init) end + --- --- Returns a copy of `s` in which all (or the first `n`, if given) --- occurrences of the `pattern` have been replaced by a replacement string @@ -230,9 +237,9 @@ function string.match(s, pattern, init) end --- Returns a binary string containing the values `v1`, `v2`, etc. packed (that --- is, serialized in binary form) according to the format string `fmt`. ---@param fmt string ----@param v1 string ----@param v2? string ----@param ... string +---@param v1 string|number|integer +---@param v2? string|number|integer +---@param ... string|number|integer ---@return string function string.pack(fmt, v1, v2, ...) end diff --git a/crates/emmylua_code_analysis/resources/std/table.lua b/crates/emmylua_code_analysis/resources/std/table.lua index 06d034aa4..12a142bb5 100644 --- a/crates/emmylua_code_analysis/resources/std/table.lua +++ b/crates/emmylua_code_analysis/resources/std/table.lua @@ -34,11 +34,10 @@ function table.concat(list, sep, i, j) end --- elements to `list[pos]`, `list[pos+1]`, `ยทยทยท`, `list[#list]`. The default --- value for `pos` is ``#list+1`, so that a call `table.insert(t,x)`` inserts --- `x` at the end of list `t`. ----@overload fun(list:table, value:any):integer +---@overload fun(list:table, value:any) ---@param list table ---@param pos integer ---@param value any ----@return integer function table.insert(list, pos, value) end ---@version > 5.3 @@ -100,7 +99,6 @@ function table.remove(list, pos) end ---@generic V ---@param list V[] ---@param comp? fun(a:V, b:V):boolean ----@return integer function table.sort(list, comp) end ---@version > 5.2, JIT diff --git a/crates/emmylua_code_analysis/resources/std/utf8.lua b/crates/emmylua_code_analysis/resources/std/utf8.lua index 7489ac4a7..b7d8f1513 100644 --- a/crates/emmylua_code_analysis/resources/std/utf8.lua +++ b/crates/emmylua_code_analysis/resources/std/utf8.lua @@ -40,9 +40,15 @@ utf8.charpattern = "" --- (in bytes) and `c` the code point of each character. It raises an error if --- it meets any invalid byte sequence. ---@param s string ----@return string +---@return fun(s: string, i?: integer): integer, integer function utf8.codes(s) end +---@version > 5.4 +---@param s string +---@param lax? boolean +---@return fun(s: string, i?: integer): integer, integer +function utf8.codes(s, lax) end + --- --- Returns the codepoints (as integers) from all characters in `s` that start --- between byte position `i` and `j` (both included). The default for `i` is @@ -55,6 +61,15 @@ function utf8.codes(s) end ---@return integer function utf8.codepoint(s, i, j) end +---@version > 5.4 +---@overload fun(s:string):integer +---@param s string +---@param i? integer +---@param j? integer +---@param lax? boolean +---@return integer +function utf8.codepoint(s, i, j, lax) end + --- --- Returns the number of UTF-8 characters in string `s` that start between --- positions `i` and `j` (both inclusive). The default for `i` is 1 and for @@ -63,6 +78,15 @@ function utf8.codepoint(s, i, j) end ---@param s string ---@param i? integer ---@param j? integer +---@return integer? +---@return integer? errpos +---@nodiscard +function utf8.len(s, i, j) end + +---@version > 5.4 +---@param s string +---@param i? integer +---@param j? integer ---@param lax? boolean ---@return integer? ---@return integer? errpos From f4444e952d6398c2e39c4b5ef9cc7222f5beba9b Mon Sep 17 00:00:00 2001 From: "efve.zff" Date: Mon, 2 Mar 2026 19:06:08 +0800 Subject: [PATCH 2/3] append JIT version to old debug.traceback --- crates/emmylua_code_analysis/resources/std/debug.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/emmylua_code_analysis/resources/std/debug.lua b/crates/emmylua_code_analysis/resources/std/debug.lua index 9514304de..6c9141351 100644 --- a/crates/emmylua_code_analysis/resources/std/debug.lua +++ b/crates/emmylua_code_analysis/resources/std/debug.lua @@ -294,7 +294,7 @@ function debug.setupvalue(f, up, value) end ---@return userdata? function debug.setuservalue(udata, value, n) end ----@version 5.1 +---@version 5.1, JIT --- --- Returns a string with a traceback of the call stack. An optional message --- string is appended at the beginning of the traceback. An optional level From 61eb1d2495cfe6ec3dc3e9f6aa573337852912de Mon Sep 17 00:00:00 2001 From: "efve.zff" Date: Mon, 2 Mar 2026 19:26:55 +0800 Subject: [PATCH 3/3] improve warn annotation --- crates/emmylua_code_analysis/resources/std/global.lua | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/crates/emmylua_code_analysis/resources/std/global.lua b/crates/emmylua_code_analysis/resources/std/global.lua index fcf00a75a..022b0684a 100644 --- a/crates/emmylua_code_analysis/resources/std/global.lua +++ b/crates/emmylua_code_analysis/resources/std/global.lua @@ -470,8 +470,14 @@ function unpack(list, i, j) end ---@version > 5.4 --- ----@param msg1 string ----@param ... string +--- Emits a warning with a message composed by the concatenation of all its arguments (which should be strings). +--- +--- By convention, a one-piece message starting with '@' is intended to be a control message, +--- which is a message to the warning system itself. In particular, +--- the standard warning function in Lua recognizes the control messages "@off", to stop the emission of warnings, +--- and "@on", to (re)start the emission; it ignores unknown control messages. +---@param msg1 string|number +---@param ... string|number function warn(msg1, ...) end ---@type string[]