aardio 文档

JSON 库使用指南

在 aardio 中，可以使用 JSON 库来编码（将表对象转换为 JSON 字符串）和解码（将 JSON 字符串解析为表对象）JSON 数据。

JSON 库函数参考

一. JSON 编解码 #

1. 解码 JSON（解析 JSON 字符串为表对象）

使用 JSON.parse 函数将 JSON 字符串解析为 aardio 表对象。

import JSON;
import console;

// JSON 字符串
var jsonString = `{
    "name": "John",
    "age": 30,
    "hobbies": ["reading", "swimming"]
}`;

// 解析 JSON 字符串为表对象
var obj = JSON.parse(jsonString);

// 输出解析后的对象
console.dumpJson(obj);
console.log("Name:", obj.name);
console.log("Age:", obj.age);
console.log("Hobbies:", obj.hobbies);

console.pause();

JSON.parse 函数在解析出错时会抛出异常， JSON.tryParse 函数用法相同但在解析出错时会返回 null 值而非报错。

2. 编码 JSON（将表对象转换为 JSON 字符串）#

使用 JSON.stringify 函数将 aardio 表对象转换为 JSON 字符串。

import JSON;

// 表对象
var obj = {
    name = "Alice";
    age = 25;
    hobbies = ["reading", "swimming"];
};

// 将表对象转换为 JSON 字符串
var jsonString = JSON.stringify(obj, true); // 参数 @2 为 true 时格式化 JSON

// 输出 JSON 字符串
print(jsonString);

3. 读写 JSON 文件 #

编码对象并写入 JSON 文件

import JSON;

// 表对象
var data = {
    name = "Bob";
    age = 28;
    isStudent = false;
};

// 将表对象转换为 JSON 字符串并保存到文件
JSON.save("/path/to/file.json", data);

读取并解析 JSON 文件

import JSON;
import console;

// 读取 JSON 文件并转换为表对象
var loadedObject = JSON.load("/path/to/file.json");

// 输出解析后的对象
console.dumpJson(loadedObject);
console.pause();

二. 类据类型转换要点 #

1. 区分 JSON 对象与数组

在 aardio 中对象与数组的数据类型都是表（ table ）。 表可以包含数组成员，也可以包含键值对成员，只有在包含数组时才会被处理为 JSON 数组。 使用 {} 构造的空表处理为 JSON 空对象。

在 aardio 中也可以使用 [] 或 table.array() 函数构造 纯数组。 aardio 纯数组在 JSON 中总是被处理为数组，aardio 使用 [] 构造的空数组在 JSON 中也会被处理为空数组 []。

而 JSON 数组也会被解析为 aardio 纯数组，JSON 解析得到的数组默认会添加 length 元属性并指定解析时的数组长度（以处理 null 值）。length 元属性只对 table.eachIndex,table.len 或 JSON 库函数有效。需要注意的是表经过序列化复制（例如作为线程参数传递）会移除元表。

aardio 中存在很多其他来源的数组（例如 COM 数组，封装外部对象的数组）并不一定符合上面的规则。 JSON 使用 table.type() 函数来检测一个表是否应当被处理为数组。详细规则请查看 table.type() 函数的说明。

也可以使用 JSON.stringifyArray({}) 强制转换表为 JSON 数组。

2. 保存对象的 null 值。

在 aardio 中 null 是一个不存在的值。 例如 { name = null } 等价于空表 {} 。

而在 JSON 中我们有时候需要保存 null 值。 这在 aardio 中很困难，但我们可以解决这个问题。

例如以下 aardio 代码：

//定义 JSON
var json = "{name:null,age:22}";

//解析为对象
var object = JSON.parse(json);

//生成 JSON 
var json = JSON.stringify(object);

可以正确地保存 name 的 null 值。

aardio 通过在元表的 _defined 字段中指定必须保存 null 值的字段名。 可以调用 table.define() 定义需要保留 null 值的键名（可以重复调用以添加键名）。 JSON 库 或 table.eachName 支持 _defined 元属性。

3. 时间 与 buffer 对象

buffer,time 对象与 JS 一样只负责字符串化，不负责在解析 JSON 时自动还原。

时间对象与 JS 语言相同转换为 ISO8601 格式字符串， 可使用 time.iso8601 函数解析并还原 iso8601 格式的时间对象。

buffer 类与 node.js 中的 Buffer 类相同,转换结果示例： {"data":[230,181,139],"type":"Buffer"} 其中 type 指明类型,data 为字节串（ buffer 类型）转换得到的字节数组（ table 类型）。 这种表可以作为 raw.buffer 的唯一参数快速还原为 buffer 类型。

三. aardio 标准库 JSON 解析规范 #

发布日期：2020-12-27

JSON 字符串化时完全符合 JSON 官方标准( https://json.org/json-zh.html )。 JSON 解析时完全支持 JSON，JSONP，并使用宽松的原则兼容JSON5，兼容部分类 YAML 语法。

aardio 以“宽进严出、简洁高效”为基本原则。 解析时规则尽可能宽松容错，生成 JSON 字符串则严格遵守标准 JSON 规则。

aardio 标准库在遵守 JSON 标准协议的前提下为 JSON 解析器扩展了以下功能：

1. 可省略和替换的格式标记

2. 根节点

3. 字符串

字符串置于双引号中时支持 JSON 转义符。 JSON 字符串置于单引号内不支持 JSON 转义符，使用 2 个单引号表示原始单引号。 在引号内部时字符串可以换行。

要特别注意 aardio 语法规则正好跟上面相反： aardio 代码里单引号内是“编译时转义字符串”（反斜杆识别为转义符，属于 “JavaScript 风格字符串” ），而双引号内是原样字符串（编译时将反斜杆作为普通字符，并以两个双引号表示原始双引号,属于 “BASIC/SQL 风格” 字符串）。

JSON 字符串可省略首尾引号，此时不支持 JSON 转义符，遇到回车或换行、逗号、中括号、大括号时字符串结束解析。字符串作为对象键名如果省略引号时不能包含空白字符、换行或键值分隔符。

4. 注释

1、支持 // 或 # 引导的单行注释 2、支持包含于 /*......*/ 内的块注释（注意这里按js规则不匹配首尾星号数目）。

5. 数值

数值支持 16 进制

6. null值

可以使用 null,undefined,~ 表示 null 值。

7. 日期时间

可使用 ISO 8601 格式表示日期时间，合法的格式如下：

2021-01-1 2021-02-1T15:02:31+08:00 2021-02-1T15:02:31+08:00Z

数字前可不用补 0，但日期分隔符必须使用短横线，时间分隔符必须使用冒号， 尾部时区不可以包含空白字符，但可以包含 +-: 等字符以及数字、字母。

日期时间不用包含在引号内，引号内会被误别为字符串，示例：

{"time":2021-01-1,"string":"2021-01-1" }

aardio 开发环境的相关工具与范例 #

Markdown 格式