生态言据

流与结构化错误

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

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

「事件」「启动」「序号」1
「事件」「就绪」「序号」2
「警告」3

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

增量解析

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

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

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

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

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

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

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

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

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

不抛错解析

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

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

捕获结构化错误

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


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

错误详情包含:

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

常用代码包括YJ_PARSEYJ_TYPEYJ_SCHEMAYJ_PATHYJ_MERGEYJ_PATCHYJ_PATCH_CONFLICTYJ_LIMIT_CONFIGYJ_SIZEYJ_DEPTHYJ_ITEMSYJ_CANONICALYJ_JSONYJ_TOMLYJ_STREAMYJ_IO。程序应判断 代码,不要解析可能随版本改进的消息