---@meta yaml

--------------------------------------------------------------------------------
-- LibYAML C 绑定模块
--------------------------------------------------------------------------------

---@alias yaml_encoding 'ANY'|'UTF8'|'UTF16LE'|'UTF16BE'
---@alias yaml_scalar_style 'ANY'|'PLAIN'|'SINGLE_QUOTED'|'DOUBLE_QUOTED'|'LITERAL'|'FOLDED'
---@alias yaml_collection_style 'ANY'|'BLOCK'|'FLOW'
---@alias yaml_event_type 'STREAM_START'|'STREAM_END'|'DOCUMENT_START'|'DOCUMENT_END'|'ALIAS'|'SCALAR'|'SEQUENCE_START'|'SEQUENCE_END'|'MAPPING_START'|'MAPPING_END'
---@alias yaml_token_type 'STREAM_START'|'STREAM_END'|'VERSION_DIRECTIVE'|'TAG_DIRECTIVE'|'DOCUMENT_START'|'DOCUMENT_END'|'BLOCK_SEQUENCE_START'|'BLOCK_MAPPING_START'|'BLOCK_END'|'FLOW_SEQUENCE_START'|'FLOW_SEQUENCE_END'|'FLOW_MAPPING_START'|'FLOW_MAPPING_END'|'BLOCK_ENTRY'|'FLOW_ENTRY'|'KEY'|'VALUE'|'ALIAS'|'ANCHOR'|'TAG'|'SCALAR'

---@class yaml_mark*
---@field index integer 字节偏移
---@field line integer 行号，从 0 开始
---@field column integer 列号，从 0 开始

---@class yaml_version_directive*
---@field major integer 主版本
---@field minor integer 次版本

---@class yaml_tag_directive*
---@field handle string tag 句柄
---@field prefix string tag 前缀

---@class yaml_marked*
---@field start_mark? yaml_mark* 起始位置
---@field end_mark? yaml_mark* 结束位置

---@class yaml_stream_start_event*: yaml_marked*
---@field type 'STREAM_START'
---@field encoding yaml_encoding 编码

---@class yaml_stream_end_event*: yaml_marked*
---@field type 'STREAM_END'

---@class yaml_document_start_event*: yaml_marked*
---@field type 'DOCUMENT_START'
---@field implicit? boolean 是否隐式开始
---@field version_directive? yaml_version_directive* YAML 版本指令
---@field tag_directives? yaml_tag_directive*[] tag 指令列表

---@class yaml_document_end_event*: yaml_marked*
---@field type 'DOCUMENT_END'
---@field implicit? boolean 是否隐式结束

---@class yaml_alias_event*: yaml_marked*
---@field type 'ALIAS'
---@field anchor string 锚点名

---@class yaml_scalar_event*: yaml_marked*
---@field type 'SCALAR'
---@field anchor? string 锚点名
---@field tag? string 完整 tag
---@field value string 标量文本
---@field plain_implicit? boolean plain 形式是否隐式
---@field quoted_implicit? boolean quoted 形式是否隐式
---@field style? yaml_scalar_style 标量样式

---@class yaml_sequence_start_event*: yaml_marked*
---@field type 'SEQUENCE_START'
---@field anchor? string 锚点名
---@field tag? string 完整 tag
---@field implicit? boolean 是否隐式 tag
---@field style? yaml_collection_style 序列样式

---@class yaml_sequence_end_event*: yaml_marked*
---@field type 'SEQUENCE_END'

---@class yaml_mapping_start_event*: yaml_marked*
---@field type 'MAPPING_START'
---@field anchor? string 锚点名
---@field tag? string 完整 tag
---@field implicit? boolean 是否隐式 tag
---@field style? yaml_collection_style 映射样式

---@class yaml_mapping_end_event*: yaml_marked*
---@field type 'MAPPING_END'

---@alias yaml_event yaml_stream_start_event*|yaml_stream_end_event*|yaml_document_start_event*|yaml_document_end_event*|yaml_alias_event*|yaml_scalar_event*|yaml_sequence_start_event*|yaml_sequence_end_event*|yaml_mapping_start_event*|yaml_mapping_end_event*

---@class yaml_stream_start_token*: yaml_marked*
---@field type 'STREAM_START'
---@field encoding yaml_encoding 编码

---@class yaml_simple_token*: yaml_marked*
---@field type yaml_token_type token 类型

---@class yaml_version_directive_token*: yaml_marked*
---@field type 'VERSION_DIRECTIVE'
---@field major integer 主版本
---@field minor integer 次版本

---@class yaml_tag_directive_token*: yaml_marked*
---@field type 'TAG_DIRECTIVE'
---@field handle string tag 句柄
---@field prefix string tag 前缀

---@class yaml_alias_token*: yaml_marked*
---@field type 'ALIAS'
---@field value string 锚点引用

---@class yaml_anchor_token*: yaml_marked*
---@field type 'ANCHOR'
---@field value string 锚点名

---@class yaml_tag_token*: yaml_marked*
---@field type 'TAG'
---@field handle string tag 句柄
---@field suffix string tag 后缀

---@class yaml_scalar_token*: yaml_marked*
---@field type 'SCALAR'
---@field value string 标量文本
---@field length integer 标量长度
---@field style yaml_scalar_style 标量样式

---@alias yaml_token yaml_stream_start_token*|yaml_simple_token*|yaml_version_directive_token*|yaml_tag_directive_token*|yaml_alias_token*|yaml_anchor_token*|yaml_tag_token*|yaml_scalar_token*

---@class yaml_emitter*
---@field emit fun(event:yaml_event):boolean,string? 发送一个事件；STREAM_END 时第二返回值为 YAML 文本，失败时第二返回值为错误信息
---@field errthread thread 错误缓冲线程
---@field outputthread thread 输出缓冲线程

---@class yaml*
---@field version string C 绑定版本信息
---@type yaml*
local M = {}

--- 创建 YAML token 扫描器。
---@param s string YAML 文本
---@return fun():yaml_token? next 每次调用返回下一个 token
function M.scanner(s) end

--- 创建 YAML 事件解析器。
---@param s string YAML 文本
---@return fun():yaml_event? next 每次调用返回下一个事件
function M.parser(s) end

--- 创建 YAML 事件发射器。
---@return yaml_emitter* emitter 事件发射器
function M.emitter() end

return M
