# libcJSON — JSON 解析/生成库 API 参考

## 模块概述

libcJSON 是开源的轻量级 JSON 解析/生成库（MIT 许可证），直接使用原工程版本。
基于递归下降解析器 + 树状内存模型。支持 object/array/string/number/boolean/null。

## 数据结构

```c
typedef enum
{   CJSON_NULL = 0, CJSON_FALSE, CJSON_TRUE,
    CJSON_NUMBER, CJSON_STRING, CJSON_ARRAY, CJSON_OBJECT
} enum_cjson_type;

typedef struct cjson
{
    struct cjson   *next, *prev;  // 兄弟节点链表
    struct cjson   *child;        // 子节点（对象/数组的第一个子元素）
    enum_cjson_type type;
    char            *key;         // 对象键名
    char            *val_str;     // 字符串值
    double           val_num;     // 数值
} stru_cjson;
```

## 接口函数

### 解析与释放

| 函数 | 说明 |
|------|------|
| `cJSON_Parse(json)` | 解析 JSON 字符串，返回根节点 |
| `cJSON_Delete(node)` | 递归释放整棵树 |

### 查询

| 函数 | 说明 |
|------|------|
| `cJSON_GetObjectItem(obj, key)` | 按 key 获取对象成员 |
| `cJSON_GetArraySize(arr)` | 获取数组长度 |
| `cJSON_GetArrayItem(arr, idx)` | 获取数组元素（0-based） |
| `cJSON_GetStringValue(it)` | 获取字符串值 |
| `cJSON_GetNumberValue(it)` | 获取数值 |

### 创建

| 函数 | 说明 |
|------|------|
| `cJSON_CreateObject()` | 创建空对象 `{}` |
| `cJSON_CreateArray()` | 创建空数组 `[]` |
| `cJSON_CreateString(s)` | 创建字符串节点 |
| `cJSON_CreateNumber(n)` | 创建数值节点 |
| `cJSON_CreateBool(b)` | 创建 true/false |
| `cJSON_CreateNull()` | 创建 null |

### 修改

| 函数 | 说明 |
|------|------|
| `cJSON_AddItemToObject(obj, key, item)` | 向对象添加键值对 |
| `cJSON_AddItemToArray(arr, item)` | 向数组追加元素 |
| `cJSON_DeleteItemFromObject(obj, key)` | 删除对象成员 |

### 序列化

| 函数 | 说明 |
|------|------|
| `cJSON_Print(node)` | 序列化为紧凑 JSON 字符串（调用者 free） |

## 使用示例

```c
#include "cJSON.h"
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
    // --- 解析 JSON ---
    const char *json = "{\"name\":\"RTU\",\"addr\":1,\"items\":[1,2,3]}";
    stru_cjson *root = cJSON_Parse(json);

    const char *name = cJSON_GetStringValue(cJSON_GetObjectItem(root, "name"));
    double      addr = cJSON_GetNumberValue(cJSON_GetObjectItem(root, "addr"));

    printf("name=%s, addr=%.0f\n", name, addr);
    // 输出: name=RTU, addr=1

    // 遍历数组
    stru_cjson *arr = cJSON_GetObjectItem(root, "items");
    int n = cJSON_GetArraySize(arr);
    for (int i = 0; i < n; i++)
    {
        printf("  [%d] = %.0f\n", i,
               cJSON_GetNumberValue(cJSON_GetArrayItem(arr, i)));
    }

    cJSON_Delete(root);

    // --- 创建 JSON ---
    stru_cjson *obj = cJSON_CreateObject();
    cJSON_AddItemToObject(obj, "status", cJSON_CreateString("ok"));
    cJSON_AddItemToObject(obj, "code",   cJSON_CreateNumber(200));

    char *out = cJSON_Print(obj);
    printf("生成的 JSON: %s\n", out);  // {"status":"ok","code":200}
    free(out);
    cJSON_Delete(obj);

    return 0;
}
```

## 依赖关系

- **依赖**: `stdlib.h`, `string.h`, `stdio.h`, `math.h`
- **被依赖**: 配置文件解析、Web API 交互 等模块