TOML文件

一种简洁、易读、面向配置文件的标记语言
设计目标是平衡“人类可读性”与“机器可解析性”
避免 YAML 的缩进陷阱和 JSON 对注释的缺失。。

一、基础规则

在学习具体语法前，需掌握所有 TOML 文档的通用规则：

编码格式：必须使用 UTF-8 编码（无 BOM）。
大小写敏感：键名、类型（如 true/false）、日期格式等均区分大小写（例如 True 不是有效的布尔值）。
注释：
- 单行注释：使用 #，从 # 到行尾的内容均为注释（示例：# 这是一条注释）。
- 无多行注释：需每行单独加 #。
空白字符：
- 空格（）和制表符（\t）可作为分隔符或缩进（缩进仅为可读性，无语法意义）。
- 空行（仅含空白字符的行）会被忽略。
换行符：支持 \n（Unix/Linux）、\r\n（Windows）、\r（旧 Mac），推荐使用 \n。

二、核心数据类型

TOML 支持 8 种基础数据类型，每种类型有明确的语法规则，以下按使用频率排序：

1. 字符串（String）

字符串是最常用的类型，支持 4 种写法，满足不同场景需求：

类型	语法格式	特点	示例
基本字符串	用双引号 `"` 包裹	支持转义字符（如 `\n`、`\"`）	`"Hello\nWorld"` → 解析后含换行
多行基本字符串	用 `""""""`（6个双引号）包裹	保留换行和空格，支持转义	`""""""Line 1\nLine 2""""""`
字面字符串	用单引号 `'` 包裹	不支持转义，原样保留内容	`'C:\Users\Tom'` → 无需转义 `\`
多行字面字符串	用 `''''''`（6个单引号）包裹	保留所有内容（含换行、空格、特殊字符）	`''''''He said "Hi!"''''''`

特殊说明：多行字符串的起始 """"""/'''''' 可单独占一行（推荐，增强可读性），例如：
```
multi_line = """
这是第一行
这是第二行（末尾的换行也会被保留）
"""
```

2. 整数（Integer）

表示无小数部分的数值，支持多种进制和格式：

十进制：直接写数字（可带正负号），示例：age = 25、temperature = -10。
二进制：前缀 0b，示例：binary = 0b1010（等于十进制 10）。
八进制：前缀 0o，示例：octal = 0o12（等于十进制 10）。
十六进制：前缀 0x，支持大小写字母，示例：hex = 0xA（等于十进制 10）、hex2 = 0xff（等于十进制 255）。
下划线分隔：可在数字中插入 _ 提升可读性（仅用于分隔，不影响数值），示例：population = 7_800_000_000。

3. 浮点数（Float）

表示带小数部分的数值，支持科学计数法：

标准格式：整数部分.小数部分，示例：pi = 3.14159、weight = 62.5。
科学计数法：用 e 或 E 表示指数（指数部分可带正负号），示例：speed = 3e8（等于 300000000）、tiny = 1.23e-4（等于 0.000123）。
特殊浮点数：
- 正无穷：inf 或 +inf
- 负无穷：-inf
- 非数（NaN）：nan 或 +nan/-nan（大小写不敏感，如 NaN 也有效）
下划线分隔：同整数，示例：distance = 1_234.567_89。

4. 布尔值（Boolean）

表示“真”或“假”，必须小写：

真值：true
假值：false
错误示例：True、FALSE 均无效。

5. 日期时间（Date & Time）

TOML 严格遵循 ISO 8601 标准，支持 4 种时间精度，格式固定（不可随意修改）：

类型	语法格式	示例
日期（Date）	`YYYY-MM-DD`	`birthday = 1990-01-01`
时间（Time）	`HH:MM:SS` 或 `HH:MM:SS.sss`（毫秒）	`start_time = 08:30:00`、`precise = 14:59:59.999`
日期时间（本地）	`YYYY-MM-DDTHH:MM:SS`（T 分隔）	`meeting = 2024-05-20T14:30:00`
日期时间（UTC）	本地格式 + `Z` 后缀	`deadline = 2024-05-31T23:59:59Z`

注意：T 是日期和时间的强制分隔符，不可用空格代替；UTC 时间的 Z 后缀必须大写。

6. 数组（Array）

有序的同类型（推荐）或不同类型元素集合，用方括号 [] 包裹：

基础语法：元素用逗号 , 分隔，末尾可加逗号（允许 trailing comma）。

fruits = ["apple", "banana", "orange"]  # 字符串数组
numbers = [1, 2, 3, 4]                  # 整数数组
mixed = [1, "two", true]                # 混合类型数组（语法允许，但不推荐）

多行数组：可换行书写，缩进不影响语法，示例：

colors = [
  "red",
  "green",
  "blue",  # 末尾逗号允许
]

嵌套数组：数组内可包含其他数组（多维数组），示例：
```
matrix = [
  [1, 2, 3],
  [4, 5, 6],
]
```

三、结构类型（组织数据的方式）

TOML 通过“表”和“数组表”实现层级结构，替代 JSON 的“对象”和“对象数组”。

1. 表（Table）：对应 JSON 对象

表是 键值对的集合，用 [表名] 定义（称为“表头”），作用是将相关键值对分组，避免键名冲突。

1.1 基础表（单层表）

语法：[表名]，表名由字母、数字、下划线、连字符（-）组成，示例：

# 基础表：存储用户信息
[user]
name = "Alice"
age = 30
email = "alice@example.com"

# 基础表：存储配置信息
[config]
theme = "dark"
notifications = true

解析为 JSON 等价于：

{
  "user": { "name": "Alice", "age": 30, "email": "alice@example.com" },
  "config": { "theme": "dark", "notifications": true }
}

1.2 嵌套表（多层表）

有两种写法，用于表示多层级结构：

显式嵌套：通过 . 分隔表名，示例：

# 嵌套表：user 的地址信息（等价于 user.address）
[user.address]
city = "Beijing"
street = "Main Street"
zipcode = "100000"

隐式嵌套：先定义父表，再定义子表（与显式效果一致），示例：
```
[user]
name = "Bob"

[user.address]  # 隐
```

Keyboard shortcuts

技术文档