TOML 介绍

发表于 分类于 阅读次数： 本文字数： 4.8k
TOML 介绍与基本语法

TOML 的简介

TOML (Tom’s Obvious Minimal Language) Tom 的（语义）明显、（配置）最小化的语言。

TOML 旨在成为一个语义明显且易于阅读的最小化配置文件格式。TOML 被设计成可以无歧义地映射为哈希表。TOML 应该能很容易地被解析成各种语言中的数据结构。

备注：Tom 代表 Tom Preston-Werner ，GitHub 的联合创始人之一。

TOML 的特性

  • TOML 是大小写敏感的
  • TOML 文件的编码格式是 UTF-8
  • TOML 文件的扩展名是 .toml
  • TOML 文件的 MIME 类型是 application/toml

TOML 的例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# This is a TOML document

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [ 8000, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]
temp_targets = { cpu = 79.5, case = 72.0 }

[servers]

[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"

以上 TOML 转换为 JSON 数据结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
    "title": "TOML Example",
    "owner": {
        "name": "Tom Preston-Werner",
        "dob": "1979-05-27T07:32:00-08:00"
    },
    "database": {
        "enabled": true,
        "ports": [
            8000,
            8001,
            8002
        ],
        "data": [
            [
                "delta",
                "phi"
            ],
            [
                3.14
            ]
        ],
        "temp_targets": {
            "cpu": 79.5,
            "case": 72.0
        }
    },
    "servers": {
        "alpha": {
            "ip": "10.0.0.1",
            "role": "frontend"
        },
        "beta": {
            "ip": "10.0.0.2",
            "role": "backend"
        }
    }
}

TOML 的基本语法

注释

TOML 使用 # 符号作为注释的开始，直到行尾的内容都是注释。

除制表符以外的控制字符（U+0000 至 U+0008，U+000A 至 U+001F，U+007F）不允许出现在注释中。

1
2
3
# 这是一个全行注释
key = "value"  # 这是一个行末注释
another = "# 这不是一个注释"

键值对

  • TOML 文档最基本的构成区块是键值对。键值对由键名、等号、值组成
  • 键名在等号的左边而值在右边
  • 键名和键值周围的空白会被忽略 (意味着可以进行任意缩进而不影响解析)
  • 键、等号和值必须在同一行（不过有些值可以跨多行）

TOML 中的键

键名可以是裸露的，引号引起来的，或点分隔的。

  • 裸露的键名是由 ASCII 字母、数字、下划线和连字符 (a-z/A-Z/0-9/_/-) 组成的字符串
  • 注意裸键允许仅由纯 ASCII 数字构成，例如 1234，但总是被解释为字符串。
1
2
3
4
abc123 = "value"
ab_c = "value"
ab-c = "value"
1234 = "value"

以上 toml 等价于如下 json：

1
2
3
4
5
6
{
    "abc123": "value",
    "ab_c": "value",
    "ab-c": "value",
    "1234": "value"
}
  • 引号键遵循与基本字符串或字面量字符串相同的规则并允许你使用更为广泛的键名
  • 除非明显必要，使用裸键方为最佳实践
  • 裸键不能为空，但空引号键是允许的（虽然不建议如此）
1
2
3
"abc" = "value"
"王大锤" = "value"
"" = "value" # 合法但不推荐
  • 点分隔键是一系列通过点相连的裸键或引号键
  • 这允许了你将相近属性放在一起
1
2
3
4
name = "Orange"
physical.color = "orange"
physical.shape = "round"
site."google.com" = true

以上 toml 等价于如下 json：

1
2
3
4
5
6
7
8
9
10
{
    "name": "Orange",
    "physical": {
        "color": "orange",
        "shape": "round"
    },
    "site": {
        "google.com": true
    }
}

TOML 中的值

关于 TOML 中的值的详细介绍请参考 TOML 中文文档

字符串

1
str = "I'm a string. \"You can quote me\". Name\tJos\u00E9\nLocation\tSF."

整数

1
2
3
4
5
int1 = +99
int2 = 42
int3 = 0
int4 = -17
int5 = 1_000

浮点数

1
2
3
4
5
6
7
8
9
10
11
12
# 小数
flt1 = +1.0
flt2 = 3.1415
flt3 = -0.01

# 指数
flt4 = 5e+22
flt5 = 1e06
flt6 = -2E-2

# 都有
flt7 = 6.626e-34

布尔值

1
2
bool1 = true
bool2 = false

日期时间

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 带有时区
odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
odt3 = 1979-05-27T00:32:00.999999-07:00
odt4 = 1979-05-27 07:32:00Z

# 不带时区
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999

# 日期
ld1 = 1979-05-27

# 时间
lt1 = 07:32:00
lt2 = 00:32:00.999999

数组

1
2
3
4
5
6
7
8
9
10
11
12
integers = [ 1, 2, 3 ]
colors = [ "红", "黄", "绿" ]
nested_array_of_ints = [ [ 1, 2 ], [3, 4, 5] ]
nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
string_array = [ "所有的", '字符串', """是相同的""", '''类型''' ]

# 允许混合类型的数组
numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
contributors = [
  "Foo Bar <foo@example.com>",
  { name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" }
]

表

1
2
3
4
5
6
7
8
9
[fruit]
apple.color = "红"
apple.taste.sweet = true

# [fruit.apple]  # 非法
# [fruit.apple.taste]  # 非法

[fruit.apple.texture]  # 你可以添加子表
smooth = true

等价于如下 json：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "fruit": {
        "apple": {
            "color": "红",
            "taste": {
                "sweet": true
            },
            "texture": {
                "smooth": true
            }
        }
    }
}

内联表

1
2
3
name = { first = "Tom", last = "Preston-Werner" }
point = { x = 1, y = 2 }
animal = { type.name = "pug" }

等价于如下表：

1
2
3
4
5
6
7
8
9
10
[name]
first = "Tom"
last = "Preston-Werner"

[point]
x = 1
y = 2

[animal]
type.name = "pug"

表数组

1
2
3
4
5
6
7
8
9
10
11
[[products]]
name = "Hammer"
sku = 738594937

[[products]]  # 数组里的空表

[[products]]
name = "Nail"
sku = 284758393

color = "gray"

等价于如下 json：

1
2
3
4
5
6
7
8
9
10
11
12
[
    {
        "name": "Hammer",
        "sku": 738594937
    },
    {},
    {
        "name": "Nail",
        "sku": 284758393,
        "color": "gray"
    }
]