aardio 文档

JSON 库使用指南

在 aardio 中，可以使用 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 开发环境的相关工具与范例 #

Markdown 格式