---@meta argchecker

--------------------------------------------------------------------------------
-- Parameter Inspector module
--------------------------------------------------------------------------------

---@alias argchecker_expected_type string

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

--- Throws a Lua-style bad argument error.
---@param field string? Function name; if nil, try to infer from the call stack
---@param arg_count integer Parameter number
---@param mean string Parameter meaning, such as `(path)`; can be an empty string
---@param expected_type argchecker_expected_type Desired type description
---@param got_type string Actual type description; may be empty string
---@param level_plus? integer Additional call stack levels
function M.bad_arg(field, arg_count, mean, expected_type, got_type, level_plus) end

--- Checks the required parameters at the specified location.
---
--- When `expected_type` contains `integer` or `number`, the corresponding numeric type will be returned when convertible;
--- When `string` is included, string/number will be converted to string.
---@param arg_count integer Parameter number, starting from 1
---@param expected_type argchecker_expected_type Desired type description
---@param ... any List of parameters to be checked
---@return any value Checked or converted value
function M.check_value(arg_count, expected_type, ...) end

--- Check the required parameters at the specified location, and specify the error function name and parameter description.
---
--- When `expected_type` contains `integer` or `number`, the corresponding numeric type will be returned when convertible;
--- When `string` is included, string/number will be converted to string.
---@param field string function name
---@param arg_count integer Parameter number, starting from 1
---@param mean string Parameter meaning, such as `(path)`; can be an empty string
---@param expected_type argchecker_expected_type Desired type description
---@param ... any List of parameters to be checked
---@return any value Checked or converted value
function M.check_value_ex(field, arg_count, mean, expected_type, ...) end

--- Checks the optional parameters at the specified location.
---
--- Returns `default_val` when the argument is missing or nil. When `expected_type` contains `integer` or `number`,
--- The corresponding numeric type will be returned when convertible; when `string` is included, string/number will be converted to string.
---@generic T
---@param arg_count integer Parameter number, starting from 1
---@param expected_type argchecker_expected_type Desired type description
---@param default_val T Default value
---@param ... any List of parameters to be checked
---@return T|any value Checked or converted value
function M.opt_value(arg_count, expected_type, default_val, ...) end

--- Check the optional parameters at the specified location, and specify the error function name and parameter description.
---
--- Returns `default_val` when the argument is missing or nil. When `expected_type` contains `integer` or `number`,
--- The corresponding numeric type will be returned when convertible; when `string` is included, string/number will be converted to string.
---@generic T
---@param field string function name
---@param arg_count integer Parameter number, starting from 1
---@param mean string Parameter meaning, such as `(path)`; can be an empty string
---@param expected_type argchecker_expected_type Desired type description
---@param default_val T Default value
---@param ... any List of parameters to be checked
---@return T|any value Checked or converted value
function M.opt_value_ex(field, arg_count, mean, expected_type, default_val, ...) end

return M
