TOON

简体中文

English

简体中文

English

外观

语法速查表 ​

将 JSON 映射为 TOON 格式的快速参考。关于严谨的规范性语法规则和边界情况,请参阅 规范。

对象 ​

json
{
  "id": 1,
  "name": "Ada"
}
yaml
id: 1
name: Ada

嵌套对象 ​

json
{
  "user": {
    "id": 1,
    "name": "Ada"
  }
}
yaml
user:
  id: 1
  name: Ada

基本类型数组 ​

json
{
  "tags": ["foo", "bar", "baz"]
}
yaml
tags[3]: foo,bar,baz

表格化数组 ​

json
{
  "items": [
    { "id": 1, "qty": 5 },
    { "id": 2, "qty": 3 }
  ]
}
yaml
items[2]{id,qty}:
  1,5
  2,3

混合与非一致数组 ​

json
{
  "items": [1, { "a": 1 }, "x"]
}
yaml
items[3]:
  - 1
  - a: 1
  - x

NOTE

当一个列表项对象的第一个字段是表格化数组时,表格化头部会出现在连字符所在的那一行。行数据比连字符深两级缩进,其他字段深一级缩进。这是该模式的规范编码方式。

yaml
items[1]:
  - users[2]{id,name}:
      1,Ada
      2,Bob
    status: active
yaml
items[1]:
  - users[2]{id,name}:
      1,Ada
      2,Bob

数组的数组 ​

json
{
  "pairs": [[1, 2], [3, 4]]
}
yaml
pairs[2]:
  - [2]: 1,2
  - [2]: 3,4

根数组 ​

json
["x", "y", "z"]
yaml
[3]: x,y,z

空容器 ​

json
{}
yaml
(空输出)
json
{
  "items": []
}
yaml
items: []

引号的特殊情况 ​

看起来像字面量的字符串 ​

json
{
  "version": "123",
  "enabled": "true"
}
yaml
version: "123"
enabled: "true"

这些字符串必须加引号,因为它们看起来像数字/布尔值。

包含分隔符的字符串 ​

json
{
  "note": "hello, world"
}
yaml
note: "hello, world"

当字符串包含生效分隔符(在数组作用范围内)或文档级分隔符(对象字段的值,默认为逗号)时,必须加引号。

带前导/尾随空格的字符串 ​

json
{
  "message": " padded "
}
yaml
message: " padded "

空字符串 ​

json
{
  "name": ""
}
yaml
name: ""

引号规则汇总 ​

在以下情况下,字符串必须加引号:

  • 为空字符串("")
  • 存在前导或尾随空白
  • 等于 true、false 或 null(区分大小写)
  • 看起来像数字(例如 "42"、"-3.14"、"1e-6"、"05")
  • 包含特殊字符::、"、\、[、]、{、},或任何控制字符(U+0000–U+001F,包括换行符/制表符/回车符)
  • 包含相关的分隔符——数组作用范围内的生效分隔符,或对象字段值的文档级分隔符(默认为逗号)
  • 等于 "-",或以 "-" 开头且后面还有其他字符

除此之外,字符串都可以不加引号。Unicode 和 emoji 是安全的:

yaml
message: Hello 世界 👋
note: This has inner spaces

转义序列 ​

在带引号的字符串中,有六种合法的转义序列:

字符转义
反斜杠(\)\\
双引号(")\"
换行符\n
回车符\r
制表符\t
其他任意 U+0000–U+001F 控制字符\uXXXX

其他转义方式(例如 \x、\0、\b)是非法的,单独出现的代理项 \uXXXX 值(U+D800–U+DFFF)会被拒绝。

数组头部 ​

基础头部 ​

key[N]:
  • N = 数组长度
  • 默认分隔符:逗号

表格化头部 ​

key[N]{field1,field2,field3}:
  • N = 数组长度
  • {fields} = 列名
  • 默认分隔符:逗号

备选分隔符 ​

yaml
items[2	]{id	name}:
  1	Alice
  2	Bob
yaml
items[2|]{id|name}:
  1|Alice
  2|Bob

分隔符符号出现在方括号和花括号内部。

键折叠(可选) ​

标准嵌套:

yaml
data:
  metadata:
    items[2]: a,b

启用键折叠后(keyFolding: 'safe'):

yaml
data.metadata.items[2]: a,b

详情请参阅 格式概览——键折叠。

类型转换 ​

输入输出
位于 [1e-6, 1e21) 范围内(或为零)的有限数字规范的十进制形式
超出该范围的有限数字允许使用指数记法
NaN、Infinity、-Infinitynull
BigInt(安全范围内)数字
BigInt(超出范围)带引号的十进制字符串
DateISO 字符串(带引号)
Set归一化后的值组成的数组
Map以 String(key) 为键的对象
undefined、function、symbolnull

INFO

TOON 本身并未规定 Date 应如何编码——规范将其留给具体实现决定。本库以带引号的 ISO 8601 字符串形式输出;其他实现可能会有不同的选择。