JSON / JSON5 操作

可用性：两个变体（Full / Tiny）均支持；独立于会话可用——无需启动任何 OnePath 会话即可使用。

OnePath 内置一组 JSON/JSON5 解析与操作 API（onepath_json.h）。该 API 可在不启动任何 OnePath 会话的情况下使用，适合配置处理、消息体编解码等场景。

一、设计要点

• 独立：不依赖 OnePath 会话，可单独使用 JSON 解析和操作。
• JSON5 兼容：支持注释（//、/* */）、尾逗号等 JSON5 超集特性。
• 层级路径：用 / 分隔对象键，[N] 访问数组索引。
• 所有权清晰：onepath_json_parse() 在堆上分配，onepath_json_free() 释放。

二、快速上手

#include <onepath.h>  /* 自动包含 onepath_json.h */

int main(void) {
    /* 解析 JSON5 字符串 */
    const char *input = "{/* config */ \"host\": \"example.com\", \"port\": 8080}";
    onepath_json_t *doc = onepath_json_parse(input, 0);
    if (!doc) { printf("parse error\n"); return 1; }

    /* 查询 */
    onepath_json_val_t v;
    onepath_json_get(doc, "host", &v);
    printf("host = %.*s\n", (int)v.str_len, v.str);

    /* 修改 */
    onepath_json_set(doc, "port", "9090");

    /* 序列化 */
    char *buf = NULL; size_t len = 0;
    onepath_json_dump(doc, &buf, &len);
    printf("result: %s\n", buf);
    free(buf);

    onepath_json_free(doc);
    return 0;
}

配套示例程序 onepath_json_demo 给出完整可运行版本。

三、路径语法

/* 对象键 */
onepath_json_get(doc, "server", &v);        // 顶层键 "server"
onepath_json_get(doc, "nested/key", &v);    // 嵌套键 nested → key
onepath_json_get(doc, "/nested/key", &v);   // 等价, 前导 / 可选

/* 数组索引 */
onepath_json_get(doc, "tags[0]", &v);       // 数组第 0 个元素
onepath_json_get(doc, "tags[1]/sub", &v);   // 数组元素中的对象键

四、限制与注意事项

1. 性能：当前实现对每个 set/delete 操作在可变文档上执行，适合配置处理和小型文档。
2. 数值类型：不区分 int/uint 字面量（正数 → UINT，负数 → INT）。
3. JSON5 子集：支持注释和尾逗号，不支持单引号字符串和十六进制数字。
4. 线程安全：API 非线程安全，多线程需用户自行加锁。

API 参考

完整函数签名、结果类型 onepath_json_val_t、类型常量与错误码见 JSON 操作 API。