---@meta lpeglabel

--------------------------------------------------------------------------------
-- LPegLabel 1.6.1 模式匹配模块
--------------------------------------------------------------------------------

---@alias lpeglabel_label string|integer
---@alias lpeglabel_match_time_function fun(subject:string, position:integer, ...:any):integer|boolean|nil, ...
---@alias lpeglabel_fold_function fun(acc:any, value:any, ...:any):any, ...
---@alias lpeglabel_capture_function fun(...:any):any, ...
---@alias lpeglabel_capture_replacement string|integer|table<any, any>|lpeglabel_capture_function
---@alias lpeglabel_pattern_convertible lpeglabel_pattern|string|number|boolean|table<any, any>|lpeglabel_match_time_function

---@class lpeglabel_pattern*
---@operator add(lpeglabel_pattern_convertible): lpeglabel_pattern
---@operator sub(lpeglabel_pattern_convertible): lpeglabel_pattern
---@operator mul(lpeglabel_pattern_convertible): lpeglabel_pattern
---@operator div(lpeglabel_capture_replacement): lpeglabel_pattern
---@operator pow(integer): lpeglabel_pattern
---@operator unm: lpeglabel_pattern
---@operator len: lpeglabel_pattern
local pattern = {}

--- 从当前位置尝试匹配 subject。
---
--- 匹配失败时返回 `nil, label, errpos`；普通失败的 label 为 `"fail"`。
---@param subject string 输入字符串
---@param init? integer 起始位置，负数从末尾计数
---@param ... any 传给 `Carg` 的额外参数
---@return any result 捕获值或下一个位置；失败时为 nil
---@return lpeglabel_label? label 失败标签
---@return integer? errpos 失败位置
function pattern:match(subject, init, ...) end

--- 输出 pattern 的树结构，用于调试。
function pattern:ptree() end

--- 输出 pattern 的字节码，用于调试。
function pattern:pcode() end

---@class lpeglabel_locale_table*
---@field alnum lpeglabel_pattern 字母或数字
---@field alpha lpeglabel_pattern 字母
---@field cntrl lpeglabel_pattern 控制字符
---@field digit lpeglabel_pattern 数字
---@field graph lpeglabel_pattern 图形字符
---@field lower lpeglabel_pattern 小写字母
---@field print lpeglabel_pattern 可打印字符
---@field punct lpeglabel_pattern 标点字符
---@field space lpeglabel_pattern 空白字符
---@field upper lpeglabel_pattern 大写字母
---@field xdigit lpeglabel_pattern 十六进制数字

---@class lpeglabel*
---@field version string LPegLabel 版本字符串
---@type lpeglabel*
local M = {}

M.version = "LPegLabel 1.6.1"

--- 从当前位置尝试匹配 subject。
---
--- 匹配失败时返回 `nil, label, errpos`；普通失败的 label 为 `"fail"`。
---@param patt lpeglabel_pattern pattern
---@param subject string 输入字符串
---@param init? integer 起始位置，负数从末尾计数
---@param ... any 传给 `Carg` 的额外参数
---@return any result 捕获值或下一个位置；失败时为 nil
---@return lpeglabel_label? label 失败标签
---@return integer? errpos 失败位置
function M.match(patt, subject, init, ...) end

--- 如果 value 是 LPegLabel pattern，返回字符串 `"pattern"`；否则返回 nil。
---@param value any 待检查值
---@return string? type 类型名
function M.type(value) end

--- 设置 LPegLabel 回溯栈上限。
---@param max integer 最大回溯层数
function M.setmaxstack(max) end

--- 将值转换为 pattern。
---
--- 字符串按字面量匹配；非负数字匹配固定字符数；负数表示否定的固定长度匹配；
--- 布尔值生成永真/永假 pattern；表会被解释为 grammar；函数会被解释为匹配时捕获。
---@param value lpeglabel_pattern_convertible 可转换为 pattern 的值
---@return lpeglabel_pattern pattern pattern
function M.P(value) end

--- 创建会抛出标签的 pattern。
---
--- 如果 grammar 中存在同名规则，该规则会作为恢复规则；否则整个匹配失败。
---@param label lpeglabel_label 标签
---@return lpeglabel_pattern pattern pattern
function M.T(label) end

--- 创建 behind predicate。
---@param patt lpeglabel_pattern_convertible pattern
---@return lpeglabel_pattern pattern pattern
function M.B(patt) end

--- 创建 grammar 变量引用。
---@param v any grammar 规则索引
---@return lpeglabel_pattern pattern pattern
function M.V(v) end

--- 创建字符范围 pattern。
---@param ... string 范围字符串，每个字符串长度为 2，例如 `"09"`、`"az"`
---@return lpeglabel_pattern pattern pattern
function M.R(...) end

--- 创建字符集合 pattern。
---@param chars string 字符集合
---@return lpeglabel_pattern pattern pattern
function M.S(chars) end

--- 创建 UTF-8 code point 范围 pattern。
---@param cp1 integer 起始 code point
---@param cp2 integer 结束 code point
---@return lpeglabel_pattern pattern pattern
function M.utfR(cp1, cp2) end

--- 创建或填充当前 locale 的字符类 pattern 表。
---@generic T: table
---@param table? T 要填充的表；省略时创建新表
---@return T|lpeglabel_locale_table table locale 字符类表
function M.locale(table) end

--- 创建简单捕获，捕获 patt 匹配到的子串。
---@param patt lpeglabel_pattern_convertible pattern
---@return lpeglabel_pattern pattern pattern
function M.C(patt) end

--- 创建参数捕获，捕获 `match` 调用中的第 n 个额外参数。
---@param n integer 额外参数序号
---@return lpeglabel_pattern pattern pattern
function M.Carg(n) end

--- 创建 back capture，捕获最近的同名 group capture。
---@param key any group capture 名称
---@return lpeglabel_pattern pattern pattern
function M.Cb(key) end

--- 创建常量捕获。
---@param ... any 常量值
---@return lpeglabel_pattern pattern pattern
function M.Cc(...) end

--- 创建 fold capture。
---@param patt lpeglabel_pattern_convertible pattern
---@param func lpeglabel_fold_function 折叠函数
---@return lpeglabel_pattern pattern pattern
function M.Cf(patt, func) end

--- 创建 group capture。
---@param patt lpeglabel_pattern_convertible pattern
---@param key? any group 名称
---@return lpeglabel_pattern pattern pattern
function M.Cg(patt, key) end

--- 创建位置捕获。
---@return lpeglabel_pattern pattern pattern
function M.Cp() end

--- 创建 substitution capture。
---@param patt lpeglabel_pattern_convertible pattern
---@return lpeglabel_pattern pattern pattern
function M.Cs(patt) end

--- 创建 table capture。
---@param patt lpeglabel_pattern_convertible pattern
---@return lpeglabel_pattern pattern pattern
function M.Ct(patt) end

--- 创建 match-time capture。
---@param patt lpeglabel_pattern_convertible pattern
---@param func lpeglabel_match_time_function 匹配时函数
---@return lpeglabel_pattern pattern pattern
function M.Cmt(patt, func) end

--- 输出 pattern 的树结构，用于调试。
---@param patt lpeglabel_pattern pattern
function M.ptree(patt) end

--- 输出 pattern 的字节码，用于调试。
---@param patt lpeglabel_pattern pattern
function M.pcode(patt) end

return M
