# TOML 快速参考

*表、字符串、数字、日期、数组*

> Source: TOML Specification (toml.io) · MIT

## 语法

### 基本规则

| Command | Description |
|---------|-------------|
| `key = value` | 键值对（每行一个） |
| `#` | 注释（到行尾） |
| `Case sensitive` | 键和值区分大小写 |
| `UTF-8` | 文件必须是合法的 UTF-8 |
| `No null` | TOML 没有 null 类型 |

### 最小示例

```
title = "My App"
debug = true
port = 8080
```

## 字符串

### 字符串类型

| Command | Description |
|---------|-------------|
| `"basic"` | 基本字符串（支持转义） |
| `'literal'` | 字面字符串（不转义） |
| `"""multi"""` | 多行基本字符串 |
| `'''multi'''` | 多行字面字符串 |

### 示例

```
basic = "Hello\nWorld"
literal = 'C:\Users\path'
multi = """
Line one
Line two"""
```

### 转义序列

| Command | Description |
|---------|-------------|
| `\n  \t  \r` | 换行、制表符、回车 |
| `\\` | 反斜杠 |
| `\uXXXX` | Unicode（4 位十六进制） |
| `\UXXXXXXXX` | Unicode（8 位十六进制） |

## 数字与布尔值

### 数字类型

| Command | Description |
|---------|-------------|
| `42` | 整数 |
| `1_000_000` | 带下划线的整数 |
| `0xff / 0o77 / 0b11` | 十六进制、八进制、二进制 |
| `3.14` | 浮点数 |
| `5e+22 / 1e-2` | 科学计数法 |
| `inf / nan` | 特殊浮点值 |
| `true / false` | 布尔值（必须小写） |

### 示例

```
count = 42
price = 19.99
hex_color = 0xFF5733
enabled = true
```

## 日期

### 日期与时间类型

| Command | Description |
|---------|-------------|
| `2026-03-26T10:30:00Z` | 带时区的日期时间（UTC） |
| `2026-03-26T10:30:00-05:00` | 带时区的日期时间（EST） |
| `2026-03-26T10:30:00` | 本地日期时间（无时区） |
| `2026-03-26` | 本地日期 |
| `10:30:00` | 本地时间 |

### 示例

```
created = 2026-03-26T10:30:00Z
birthday = 1990-05-15
alarm = 07:00:00
```

## 表

### 表语法

```
[server]
host = "localhost"
port = 8080

[server.ssl]
enabled = true
cert = "/path/to/cert.pem"
```

### 表数组

```
[[users]]
name = "Alice"
role = "admin"

[[users]]
name = "Bob"
role = "user"
```

### 规则

| Command | Description |
|---------|-------------|
| `[name]` | 标准表头 |
| `[a.b.c]` | 点号键 — 嵌套表 |
| `[[name]]` | 表数组 |
| `No redefine` | 不能重复定义同一个表 |

## 数组

### 数组语法

```
colors = ["red", "green", "blue"]
numbers = [1, 2, 3]
```

### 多行数组

```
hosts = [
  "alpha.example.com",
  "beta.example.com",
]
```

*TOML 数组允许末尾逗号*

### 规则

| Command | Description |
|---------|-------------|
| `Same type` | 所有元素必须同类型 |
| `Trailing comma` | 最后一个元素后可以有逗号 |
| `Newlines` | 数组可以跨多行 |

## 内联表

### 内联表语法

```
point = { x = 1, y = 2 }
user = { name = "Alice", admin = true }
```

### 规则

| Command | Description |
|---------|-------------|
| `Single line` | 必须写在一行内 |
| `No trailing comma` | 不允许末尾逗号 |
| `No newlines` | 不能跨多行 |
| `No adding keys` | 不能在后续再添加键 |

### 内联 vs 标准

```
# Inline — compact, one-liners
db = { host = "localhost", port = 5432 }
# Standard — readable, extendable
[db]
host = "localhost"
port = 5432
```

## 常用模式

### pyproject.toml

```
[project]
name = "myapp"
version = "1.0.0"
dependencies = ["flask>=3.0"]
```

### Cargo.toml

```
[package]
name = "myapp"
version = "0.1.0"
edition = "2021"
```

### 技巧

| Command | Description |
|---------|-------------|
| `taplo` | TOML 工具集 — 格式化与 lint |
| `No null` | 省略该键，而不是设置为 null |
| `No anchors` | 与 YAML 不同，没有引用/别名系统 |
| `Strict` | 不允许重复键，不允许混合类型数组 |