Aggrega Wasm 解析器插槽 schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/wasm-parse-v1beta1.schema.json
解析器插件插槽所消费(ParseInput)和产出(ParseOutput)的线路形态。解析器是一个无状态、无副作用的转换器,它将外部文本表示转换为规范的结构化 JSON 树,使任何语言中的任何消费者都能读取该树,而无需自带该语言的解析器。解析器在其描述符中以 parse:
以下形态之一
ParseInputParseOutput
定义
ParseInput
解析器 guest 接收的载荷:决定如何读取字节的格式名称、待解析的源字节,以及消费者为解析器特定行为提供的可选不透明选项文档。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
format | string | 是 | 要解析的源格式名称,与解析器所声明的某个 parse: |
bytes | string | 是 | 要解析的源字节。每个工具包以其自身的字段类型承载这些字节——该类型为字节类型时为原始字节,为字符串时则为 base64 编码,由解析器解码以恢复字节——生成的编码器在该字段与线路承载字节的形式之间进行转换。解析器按指定格式读取恢复后的字节。 |
options | any | 否 | 消费者为解析器特定行为提供的不透明选项文档。宿主不加解释地传递它;解析器读取其文档所说明的任何形态。消费者未提供选项时不存在。 |
不允许其他属性。
ParseOutput
解析器 guest 返回的载荷:已解析源的规范结构化树,以及解析产生的任何诊断信息和将树节点定位回原始字节的任何源范围。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
tree | any | 是 | 已解析源的规范结构化视图,形式为 JSON 文档。此处“JSON 文档”指的是解析器所产生的值的形式——这正是解析的实质目的——而非该值传输时的编码:无论此插槽通过何种线路承载,该树都是一个 JSON 文档。顶层可以是对象、数组或标量,与被解析文档自身的形态相匹配(例如,一个 JSON 文件可能解析为其中任意一种)。宿主以不透明的方式传递该树,原样承载而不解释其内容。 |
diagnostics | Diagnostic[] | 否 | 解析产生的诊断信息——例如语法错误或警告。解析未产生任何诊断信息时不存在。 |
spans | NodeSpan[] | 否 | 将树节点定位回其在原始字节中位置的源范围,使消费者能将树节点上的发现映射到源位置。解析器未报告范围时不存在。 |
error | string | 否 | 当 guest 已运行但无法完成操作时设置的失败消息;成功时不存在。它与输出携带的任何诊断信息不同:诊断信息报告的是仍产生了结果的运行中发现的问题,而 error 报告的是操作本身未能完成。宿主将存在的 error 呈现为一次失败的插件调用。 |
不允许其他属性。
NodeSpan
单个树节点的源范围:一个在树中寻址该节点的 RFC 6901 JSON Pointer,与在原始字节中定位该节点的范围配对。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
pointer | string | 是 | 指向树中的 RFC 6901 JSON Pointer,寻址此范围所定位的节点。 |
span | SourceSpan | 是 | 在原始字节中定位所寻址节点的范围。 |
不允许其他属性。
SourceSpan
原始源字节的一个范围:字节偏移量是主要的精确位置,行号和列号随之提供,用于人类可读的诊断。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
start_offset | integer | 是 | span 第一个字节在原始源中的字节偏移量,从零开始。 |
end_offset | integer | 是 | span 最后一个字节之后一个位置在原始源中的字节偏移量,因此 end_offset 减去 start_offset 即为 span 的字节长度。 |
start_line | integer | 是 | span 起始处的行号,从一开始,用于人类可读的诊断。 |
start_column | integer | 是 | span 起始处的列号,从一开始,用于人类可读的诊断。 |
end_line | integer | 是 | span 结束处的行号,从一开始,用于人类可读的诊断。 |
end_column | integer | 是 | span 结束处的列号,从一开始,用于人类可读的诊断。 |
不允许其他属性。
ParseSourceResponse
parse-source 宿主函数的回复:成功时为所解析出的解析器产生的规范结构化树,失败时为错误消息。两个字段中恰好有一个被填充。失败以带内方式传递而非通过陷阱(trap),因此消费者 guest 会将无解析器或解析失败作为确定性失败带入其自身的诊断信息。这是消费者插槽请求宿主通过宿主运行生产者时接收的信封;请求载荷为 ParseInput。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
tree | any | 否 | 成功时所解析出的解析器产生的规范结构化树,作为原样承载的 JSON 文档;失败时不存在。与解析输出自身的树一样,“JSON 文档”指的是值的形式,而非其传输时的编码。 |
error | string | 否 | 失败时的失败消息,指明格式和原因;成功时不存在。 |
hostfunc_error_code | string(枚举) | 否 | 失败时可供机器匹配的失败标识,取自封闭的宿主函数错误码目录,与人类可读的 error 消息并列设置;成功时不存在。该目录是一套固定词汇,用于命名宿主函数可能失败的方式,它与编译器登记的停机条件是不同的词汇,后者的标识符由 guest 在插槽输出中以 condition_code 和 condition_short_code 报告——键名表明一个值属于两者中的哪一个,因此两者绝不会被视为同一集合。guest 依据此代码进行分支而无需解析消息,并在代码缺失(较旧的宿主)或无法识别(较新的宿主)时回退到消息以兼容处理。允许的值:"fetch_request_unreadable"、"fetch_input_unavailable"、"fetch_failed"、"request_unreadable"、"request_undecodable"、"source_root_unavailable"、"source_read_failed"、"unknown_selection_op"、"source_escape"、"producer_consumption_reentry"、"no_source_parser"、"no_parser_for_format"、"parse_failed" |
不允许其他属性。