生态言据

流与结构化错误

有界增量处理换行分帧言据,并使用稳定错误代码诊断解析、补丁和资源失败。

言据流 v1 面向日志、进程管道和持续事件传输。它使用换行分帧:每个非空行恰好包含一个完整言据值,空行被忽略。

据【「事件」:「启动」,「序号」:1】
据【「事件」:「就绪」,「序号」:2】
列【「警告」,3】

帧内不能包含美化输出产生的原始换行;文字中的换行须写成\换。最后一帧可以没有换行,由结束输入动作提交。

增量解析

流式解析器.送入接受任意大小的文字块,并只返回已经遇到帧结束符的值。未完成的末段保存在解析器内部:

定 所流 为 言据.流式解析器();

定 首批:列 为 所流.送入("据【「序号」:1】\n据【「序号」:");
定 次批:列 为 所流.送入("2】\n");
定 末批:列 为 所流.结束();

处理外部流时应在送入第一块之前设置每帧限制:

定 所流 为 言据.流式解析器().限制({
    「最大字符」:8192,
    「最大深度」:16,
    「最大容器项」:1024
});

开始送入后不能更改限制。未结束帧持续增长到字符上限时立即返回YJ_SIZE,不等待换行; 每个完成帧还会独立检查深度和容器项总数。

结束提交无换行的最后一帧并封闭解析器。封闭后再次送入或结束会抛出YJ_STREAM。帧解析失败时,输入位置是从 1 开始的物理帧行号。

已经持有完整文字时可以使用便捷接口:

定 各值:列 为 言据.解析流(流文字);
定 流文字:文 为 言据.序列化流(各值);

不抛错解析

尝试解析总是返回一个据。成功结果为{成功:真,值,错误:空},失败结果为{成功:假,值:空,错误}:

定 结果:典 为 言据.尝试解析(外部输入);
若 结果【「成功」】则
    处理(结果【「值」】);
否则
    言 结果【「错误」】【「代码」】;
    言 结果【「错误」】【「消息」】;
终

捕获结构化错误

其他接口仍按言序的试/救机制抛出误。把捕获值传给错误详情可以得到稳定结构:

试 则
    言据.查询文(配置,「服务/证书」);
救 所误 则
    定 详情:典 为 言据.错误详情(所误);
    言 详情【「代码」】;
    言 详情【「数据路径」】;
终

错误详情包含:

字段含义
代码稳定的机器判断代码
消息面向人的中文说明
输入位置解析字符位置、TOML 行号或流帧行号;不适用时为空
数据路径已经定位到的全角斜线路径
源位置言序运行时记录的源码位置
踪迹调用踪迹

常用代码包括YJ_PARSE、YJ_TYPE、YJ_SCHEMA、YJ_PATH、YJ_MERGE、 YJ_PATCH、YJ_PATCH_CONFLICT、YJ_LIMIT_CONFIG、YJ_SIZE、YJ_DEPTH、 YJ_ITEMS、YJ_CANONICAL、YJ_JSON、YJ_TOML、YJ_STREAM和YJ_IO。程序应判断 代码,不要解析可能随版本改进的消息。