---@meta argchecker

--------------------------------------------------------------------------------
-- 参数检查器模块
--------------------------------------------------------------------------------

---@alias argchecker_expected_type string

---@class argchecker*
---@type argchecker*
local M = {}

--- 抛出 Lua 风格的 bad argument 错误。
---@param field string? 函数名；nil 时尝试从调用栈推断
---@param arg_count integer 参数序号
---@param mean string 参数含义，例如 `(path)`；可为空字符串
---@param expected_type argchecker_expected_type 期望类型描述
---@param got_type string 实际类型描述；可为空字符串
---@param level_plus? integer 额外调用栈层级
function M.bad_arg(field, arg_count, mean, expected_type, got_type, level_plus) end

--- 检查指定位置的必选参数。
---
--- `expected_type` 包含 `integer` 或 `number` 时，会在可转换时返回对应数字类型；
--- 包含 `string` 时，string/number 会转成 string。
---@param arg_count integer 参数序号，从 1 开始
---@param expected_type argchecker_expected_type 期望类型描述
---@param ... any 待检查参数列表
---@return any value 检查或转换后的值
function M.check_value(arg_count, expected_type, ...) end

--- 检查指定位置的必选参数，并指定报错函数名和参数说明。
---
--- `expected_type` 包含 `integer` 或 `number` 时，会在可转换时返回对应数字类型；
--- 包含 `string` 时，string/number 会转成 string。
---@param field string 函数名
---@param arg_count integer 参数序号，从 1 开始
---@param mean string 参数含义，例如 `(path)`；可为空字符串
---@param expected_type argchecker_expected_type 期望类型描述
---@param ... any 待检查参数列表
---@return any value 检查或转换后的值
function M.check_value_ex(field, arg_count, mean, expected_type, ...) end

--- 检查指定位置的可选参数。
---
--- 当参数缺失或为 nil 时返回 `default_val`。`expected_type` 包含 `integer` 或 `number` 时，
--- 会在可转换时返回对应数字类型；包含 `string` 时，string/number 会转成 string。
---@generic T
---@param arg_count integer 参数序号，从 1 开始
---@param expected_type argchecker_expected_type 期望类型描述
---@param default_val T 默认值
---@param ... any 待检查参数列表
---@return T|any value 检查或转换后的值
function M.opt_value(arg_count, expected_type, default_val, ...) end

--- 检查指定位置的可选参数，并指定报错函数名和参数说明。
---
--- 当参数缺失或为 nil 时返回 `default_val`。`expected_type` 包含 `integer` 或 `number` 时，
--- 会在可转换时返回对应数字类型；包含 `string` 时，string/number 会转成 string。
---@generic T
---@param field string 函数名
---@param arg_count integer 参数序号，从 1 开始
---@param mean string 参数含义，例如 `(path)`；可为空字符串
---@param expected_type argchecker_expected_type 期望类型描述
---@param default_val T 默认值
---@param ... any 待检查参数列表
---@return T|any value 检查或转换后的值
function M.opt_value_ex(field, arg_count, mean, expected_type, default_val, ...) end

return M
