xlon

裁剪与依赖

读、写和文件层可独立裁剪。只访问事件时不需要文件层，只生成内部快照时不需要 读取层。

语法

标准 JSON 类型保持原义：

扩展类型只有以下显式形式：

• bytes 使用标准、带规范填充的 Base64。
• time 使用严格 RFC 3339；写出时统一规范化为 UTC，并使用 Z。
• 有限浮点继续使用 JSON 数字；只有 nan、inf、-inf 使用 float 标签。
• intmap 键必须是 int64 整数字面量。
• set 元素必须满足 xvalue 集合的可哈希标量约束。
• 自定义标签名最长 128 字节，首字节是 ASCII 字母或下划线，后续还可使用数字、

. 和 -；载荷始终是完成 JSON 反转义的 UTF-8 字符串。

• bytes、time、float、intmap 和 set 是保留名称。

格式不支持根据第一个元素猜测容器类型，也不支持旧版 class(Base64) 原始 ABI 内存快照。空数组、空对象、空集合和空整数映射分别固定写作 []、{}、 set[]、intmap{}。

稳定契约

• 默认语法严格；注释、尾随逗号和自定义标签必须分别开启。
• 输入和字符串都使用显式长度，解码后的字符串允许包含 U+0000。
• 所有文本和标签载荷必须是合法 UTF-8，字符串转义遵守 JSON 规则。
• xrtXlonParse("null") 返回 xrtValueNull()；失败返回 C NULL。
• 整数优先无损保存为 int64，非负且超过 INT64_MAX 时保存为 uint64；超出 uint64 或低于 int64 范围默认失败。
• 读取和写出默认都有有限资源预算；配置必须先调用对应 Init。
• 事件中的字符串、字节、键、原始 token 和标签视图只在回调期间有效。
• sink 回调必须在返回前消费字节。回调设置的具体错误会保留为当前错误。
• 增量 writer 不可重入；任一失败都会进入不可恢复的失败终态。
• 文件写出先完成序列化，再原子替换目标。序列化失败不会改变已有文件。
• 模块不带隐式锁。不同解析或写入对象可并行使用，同一 writer 由调用方串行访问。

默认预算

MaxDecodedBytes 约束单个 bytes 标签的解码结果。服务端和不可信文件读取应按 实际接口进一步收紧全部预算。

读取配置

对象和 intmap 默认拒绝重复键。KEEP 保留首值并继续完整校验后续值， REPLACE 保留末值。BIGINT_FLOAT 允许把超出 uint64 或低于 int64 范围的整数有损读为 double。

自定义标签需要同时开启 XXLON_READ_CUSTOM。事件访问会直接报告 XXLON_EVENT_CUSTOM；DOM 解析还要求 Decode 返回一个拥有引用，解析器成功挂入 后接管该引用。解码器失败返回 NULL，并应设置业务错误。Reserved 必须保持零。

DOM 读取

Parse 使用默认严格配置，Read 用于语法选项、重复键、自定义标签和资源预算。 返回值由 xrtValueRelease 释放。Valid 不构造 DOM，但为字符串反转义和 bytes 语义校验可能使用可复用临时缓冲，因此不承诺零分配。

映射关系如下：

事件访问

xxloneventtype 明确区分标量事件和容器边界：

事件结构为：

Key.Type 在对象、数组、int-map 和 set 中分别是 XVALUE_KEY_STRING、 XVALUE_KEY_INDEX、XVALUE_KEY_INT 和 XVALUE_KEY_NONE。数字事件的 Raw 保留原 token，便于上层接入 BigInt 或 Decimal。

STOP 是正常提前完成。FAIL 应先设置具体业务错误；没有新错误时 XLON 层建立 XXLON_ERROR_STATE。

写出配置

ESCAPE_HTML 转义 <、>、&，但不能代替完整 HTML 上下文转义。 ESCAPE_NON_ASCII 使用 \uXXXX，补充平面字符输出代理对。

内建 XLON 可以无损写出除 Pointer、Handle 外的可移植 xvalue 类型。Pointer 和 Handle 默认失败，Encode 可把它们映射为非保留自定义标签。编码器接收只在回调 期间有效的只读快照，可以使用 Value getter；不能保存该外壳。返回的 Tag/Payload 视图必须保持到当前 WriterValue 返回。

XXLON_UNSUPPORTED_SKIP 只跳过 DOM 容器中的 Pointer/Handle 成员；根值和直接 WriterValue 仍失败。选择 SKIP 时这些成员不会再进入编码器。Indent 范围为 0 到 16，Reserved 必须保持零。

DOM 与 sink 写出

Stringify 返回由 xrtFree 释放的零结尾文本；pSize 不包含末尾零，失败时保持 不变。Write 同步提交若干借用字节块，不保留完整结果。sink 已接受的块无法撤回， 因此 sink 路径不提供事务输出。

Bytes 使用固定小块流式 Base64 编码，不建立第二份等大的 Base64 临时字符串。

增量 writer

两种 writer 共享以下操作：

Object 必须按 Name -> Value 交替写入；IntMap 按 Key -> Value 交替；Array 和 Set 直接写值。End 结束最近容器。每个 writer 只接受一个根值，全部容器关闭后使用 Finish 封闭结果。Value 在当前位置写入已有 DOM 子树。

Take 只适用于已完成的内存 writer，只能成功一次，结果由 xrtFree 释放。 sink writer 不支持 Take。Free 可接收空指针。

文件

ReadFile 在读取阶段执行 MaxInputBytes，然后使用同一配置解析。文件打开、读取、 临时文件、刷新或替换失败建立 XXLON_ERROR_IO，底层文件错误保留在原因链。

完整可运行示例位于 examples/data/xlon/main.c。