JSON / JSON5 操作 API

内置 JSON/JSON5 文档的解析、查询、修改、序列化能力。两个变体（Full / Tiny）均支持，且独立于 OnePath 会话——无需打开会话即可使用，适合配置处理、消息体编解码等场景。指南视角（设计要点、快速开始、路径语法示例）见 JSON / JSON5 操作。

数据类型

onepath_json_t

typedef struct onepath_json {
    void *doc;       /* 只读文档句柄                         */
    void *mut_doc;   /* 可变文档句柄 (写操作使用)            */
    void *mut_root;  /* 可变文档根节点                       */
    char *owned_str; /* 用户输入字符串的拷贝, NULL 表示非自有 */
} onepath_json_t;

已解析的 JSON 文档句柄（透明结构体），由 onepath_json_parse() 在堆上分配，用完后须调用 onepath_json_free() 释放。字段对用户可见，可读取以进行底层检查，但正常操作应使用提供的 API 函数。

字段	类型	说明
doc	void *	只读文档句柄
mut_doc	void *	可变文档句柄（写操作使用）
mut_root	void *	可变文档根节点
owned_str	char *	用户输入字符串的拷贝，NULL 表示非自有

onepath_json_val_t

typedef struct {
    int         type;     /* 值类型: 见 ONEPATH_JSON_TYPE_* 常量      */
    int         bool_val; /* 布尔值 (type == ONEPATH_JSON_TYPE_BOOL)  */
    int64_t     i64_val;  /* 有符号整数 (type == ONEPATH_JSON_TYPE_INT)  */
    uint64_t    u64_val;  /* 无符号整数 (type == ONEPATH_JSON_TYPE_UINT) */
    double      real_val; /* 浮点数 (type == ONEPATH_JSON_TYPE_REAL)  */
    const char *str;      /* 字符串指针 (type == ONEPATH_JSON_TYPE_STR),
                             指向文档内部内存, 不可释放              */
    size_t      str_len;  /* 字符串长度 (字节)                        */
} onepath_json_val_t;

JSON 值查询结果，由 onepath_json_get() 填充。type 字段表示实际类型，对应的 union 字段才有效。str 指针指向已解析文档内部内存，在文档释放前有效。

字段	类型	说明
type	int	值类型，见 ONEPATH_JSON_TYPE_* 常量
bool_val	int	布尔值（type == ONEPATH_JSON_TYPE_BOOL）
i64_val	int64_t	有符号整数（type == ONEPATH_JSON_TYPE_INT）
u64_val	uint64_t	无符号整数（type == ONEPATH_JSON_TYPE_UINT）
real_val	double	浮点数（type == ONEPATH_JSON_TYPE_REAL）
str	const char *	字符串指针（type == ONEPATH_JSON_TYPE_STR），指向文档内部内存，不可释放
str_len	size_t	字符串长度（字节）

整数类型

正整数字面量被解析为 UINT（type=3），负整数为 INT（type=2）。用户代码应同时检查两种类型。

生命周期

onepath_json_parse

onepath_json_t *onepath_json_parse(const char *str, size_t len);

解析 JSON / JSON5 字符串。对输入做内部拷贝，支持 JSON5 超集特性（注释、尾逗号）。

• 参数：
  • str — 以 NULL 结尾的 JSON/JSON5 字符串
  • len — 字符串长度（字节），传 0 则自动 strlen
• 返回值：解析成功返回堆分配的句柄指针，失败返回 NULL
• 注意：返回的句柄须用 onepath_json_free() 释放

onepath_json_free

void onepath_json_free(onepath_json_t *json);

释放 JSON 文档句柄及其内部资源。安全处理 NULL。

• 参数：json — 要释放的句柄，可为 NULL
• 注意：释放后句柄指针变为野指针，调用者不应再访问

查询

onepath_json_get

int onepath_json_get(const onepath_json_t *json, const char *path,
                     onepath_json_val_t *out);

按层级路径获取 JSON 值。支持简单键（abc）、嵌套键（abc/def）、数组索引（abc[0]），以及组合（abc[0]/xyz）。前导 / 可选。

• 参数：
  • json — 已解析的 JSON 文档句柄
  • path — 查询路径（如 "abc/arr[0]/key"）
  • out — 输出结果，填充 type 和对应的值字段
• 返回值：
  • ONEPATH_JSON_OK — 找到并填充 out
  • ONEPATH_JSON_EPATH — 路径语法错误
  • ONEPATH_JSON_ENOTFND — 键或索引不存在

修改

onepath_json_set

int onepath_json_set(onepath_json_t *json, const char *path,
                     const char *json_value);

在指定路径设置 JSON 值。路径上的中间对象/数组如不存在则自动创建。

• 参数：
  • json — 已解析的 JSON 文档句柄（会被修改）
  • path — 目标路径
  • json_value — 要设置的 JSON 编码值（如 "\"hello\""、"42"、"true"、"[1,2,3]"、"{\"a\":1}"）
• 返回值：
  • ONEPATH_JSON_OK — 设置成功
  • ONEPATH_JSON_EPATH — 路径语法错误
  • ONEPATH_JSON_EPARSE — value 不是合法的 JSON
  • ONEPATH_JSON_ETYPE — 路径中间节点类型不匹配（如对数组用键访问）

onepath_json_delete

int onepath_json_delete(onepath_json_t *json, const char *path);

删除指定路径的值，从父容器（对象或数组）中移除该值。对根节点调用为无操作（仅清空）。

• 参数：
  • json — 已解析的 JSON 文档句柄（会被修改）
  • path — 要删除的值的路径
• 返回值：
  • ONEPATH_JSON_OK — 删除成功
  • ONEPATH_JSON_EPATH — 路径语法错误
  • ONEPATH_JSON_ENOTFND — 键或索引不存在

序列化

onepath_json_dump

int onepath_json_dump(const onepath_json_t *json, char **buf, size_t *len);

将 JSON 文档序列化为紧凑字符串。分配新的字符串缓冲区。

• 参数：
  • json — 已解析的 JSON 文档句柄
  • buf — 输出缓冲区指针的地址（调用者 free()）
  • len — 输出字节长度（不含结尾 NULL）
• 返回值：
  • ONEPATH_JSON_OK — 成功
  • ONEPATH_JSON_ENOMEM — 内存不足
• 注意：调用者须用 free() 释放 *buf

onepath_json_dump_pretty

int onepath_json_dump_pretty(const onepath_json_t *json, char **buf,
                             size_t *len, int indent_spaces);

将 JSON 文档序列化为美化格式字符串。

• 参数：
  • json — 已解析的 JSON 文档句柄
  • buf — 输出缓冲区指针的地址（调用者 free()）
  • len — 输出字节长度（不含结尾 NULL）
  • indent_spaces — 缩进空格数（0 = 紧凑，2/4 常用）
• 返回值：
  • ONEPATH_JSON_OK — 成功
  • ONEPATH_JSON_ENOMEM — 内存不足
• 注意：调用者须用 free() 释放 *buf

错误

onepath_json_strerror

const char *onepath_json_strerror(int err);

将错误码转换为可读字符串。

• 参数：err — 错误码（ONEPATH_JSON_*）
• 返回值：指向静态字符串的指针，不可释放

值类型常量

onepath_json_val_t.type 的取值，对应有效的 union 字段：

常量	值	说明	有效字段
ONEPATH_JSON_TYPE_NULL	0	null	—
ONEPATH_JSON_TYPE_BOOL	1	true / false	bool_val
ONEPATH_JSON_TYPE_INT	2	有符号整数（int64_t）	i64_val
ONEPATH_JSON_TYPE_UINT	3	无符号整数（uint64_t）	u64_val
ONEPATH_JSON_TYPE_REAL	4	浮点数（double）	real_val
ONEPATH_JSON_TYPE_STR	5	字符串	str、str_len
ONEPATH_JSON_TYPE_ARR	6	数组	—（复合类型）
ONEPATH_JSON_TYPE_OBJ	7	对象（字典）	—（复合类型）

错误码

错误码	值	说明
ONEPATH_JSON_OK	0	成功
ONEPATH_JSON_EPARSE	-1	解析错误：无效的 JSON/JSON5 输入
ONEPATH_JSON_EPATH	-2	路径错误：路径语法非法
ONEPATH_JSON_ENOTFND	-3	未找到：键或索引不存在
ONEPATH_JSON_ENOMEM	-4	内存不足
ONEPATH_JSON_ETYPE	-5	类型不匹配

相关指南

• JSON / JSON5 操作 — 设计要点、快速开始、路径语法示例与注意事项