TOML-文件语法

TOML 官网
TOML 官方文档

介绍

TOML, Tom’s Obvious Minimal Language, 是一个语法简单易读的配置文件语言.

语法

注释

1
# This is a TOML comment

键值对

1
key = "value"

= 等号周围可以有空格. value 可以是:

  • String
  • Integer
  • Float
  • Boolean
  • Offset Date-Time
  • Local Date-Time
  • Local Date
  • Local Time
  • Array
  • Inline Table

Keys

“键” 可以是:

  • bare, 如 key = "value"
  • quoted, 如 "127.0.0.1" = "value
  • dotted, 如 physical.color = "orange"

字符串

字符串都需要是 valid UTF-8 字符, 有四种表示方式:

  • basic strings, 用双引号包裹
    1
    2
    3
    str1 = "I'm a string"
    str2 = "You can \"quote\" me."
    str3 = "Name\tJos\u00E9\nLoc\tSF."
  • multi-line basic strings, 用三个双引号包裹, 可以在行末用反斜线去掉换行符
    1
    2
    3
    4
    5
    6
    7
    8
    9
    str1 = """
    Roses are red
    Violets are blue"""

    str2 = """\
      The quick brown \
      fox jumps over \
      the lazy dog.\
      """
    str2 的值为 The quick brown fox jumps over the lazy dog..
  • literal strings, 即不会处理转义字符, 用单引号包裹
    1
    2
    3
    4
    path = 'C:\Users\nodejs\templates'
    path2 = '\\User\admin$\system32'
    quoted = 'Tom "Dubs" Preston-Werner'
    regex = '<\i\c*\s*>'
    若想在 literal strings 中使用单引号, 则需要用三个单引号包裹:
    1
    2
    3
    4
    5
    6
    7
    re = '''I [dw]on't need \d{2} apples'''
    lines = '''
    The first newline is
    trimmed in raw strings.
    All other whitespace
    is preserved.
    '''

Numbers

支持 integers, floats, infinity, 甚至 NaN, 也可以用科学记数法等:

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
39
40
41
42
43
# integers
int1 = +99
int2 = 42
int3 = 0
int4 = -17

# hexadecimal with prefix `0x`
hex1 = 0xDEADBEEF
hex2 = 0xdeadbeef
hex3 = 0xdead_beef

# octal with prefix `0o`
oct1 = 0o01234567
oct2 = 0o755

# binary with prefix `0b`
bin1 = 0b11010110

# fractional
float1 = +1.0
float2 = 3.1415
float3 = -0.01

# exponent
float4 = 5e+22
float5 = 1e06
float6 = -2E-2

# both
float7 = 6.626e-34

# separators
float8 = 224_617.445_991_228

# infinity
infinite1 = inf # positive infinity
infinite2 = +inf # positive infinity
infinite3 = -inf # negative infinity

# not a number
not1 = nan
not2 = +nan
not3 = -nan

日期

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

# local datetime
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999

# local date
ld1 = 1979-05-27

# local time
lt1 = 07:32:00
lt2 = 00:32:00.999999

Boolean

1
2
bool1 = true
bool2 = false

Array

用方括号 [] 包裹, 用逗号 , 分隔元素 (不需要是同种类型):

1
2
3
4
5
6
7
8
9
10
11
12
integers = [ 1, 2, 3 ]
colors = [ "red", "yellow", "green" ]
nested_arrays_of_ints = [ [ 1, 2 ], [3, 4, 5] ]
nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
string_array = [ "all", 'strings', """are the same""", '''type''' ]

# Mixed-type arrays are allowed
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" }
]

Table

即 Hash, dictionary, 这里的定义方式类似 section:

1
2
3
4
5
6
7
[table-1]
key1 = "some string"
key2 = 123

[table-2]
key1 = "another string"
key2 = 456

TOML 的开头默认是顶层 table, 其没有名称:

1
2
3
4
5
6
7
8
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04

(其范围直到第一个 table)

Dotted keys 也会创建 table:

1
2
3
4
5
6
7
fruit.apple.color = "red"
# Defines a table named fruit
# Defines a table named fruit.apple

fruit.apple.taste.sweet = true
# Defines a table named fruit.apple.taste
# fruit and fruit.apple were already created

Inline Table

用花括号 {} 包裹的是 inline table, 但智能写在单行, 且最后一个元素后不能加逗号 ,:

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

Inline table 不能在花括号外定义键值对:

1
2
3
[product]
type = { name = "Nail" }
# type.edible = false  # INVALID

Array of Tables

用 [[array_name]] 的语法:

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

[[products]]  # empty table within the array

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

color = "gray"

等价于:

1
2
3
4
5
6
7
{
  "products": [
    { "name": "Hammer", "sku": 738594937 },
    { },
    { "name": "Nail", "sku": 284758393, "color": "gray" }
  ]
}

对于嵌套:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[[fruits]]
name = "apple"

[fruits.physical]  # subtable
color = "red"
shape = "round"

[[fruits.varieties]]  # nested array of tables
name = "red delicious"

[[fruits.varieties]]
name = "granny smith"


[[fruits]]
name = "banana"

[[fruits.varieties]]
name = "plantain"

等价于:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "fruits": [
    {
      "name": "apple",
      "physical": {
        "color": "red",
        "shape": "round"
      },
      "varieties": [
        { "name": "red delicious" },
        { "name": "granny smith" }
      ]
    },
    {
      "name": "banana",
      "varieties": [
        { "name": "plantain" }
      ]
    }
  ]
}
Other
TOML-文件语法
http://example.com/2024/11/01/TOML-文件语法/
作者
Jie
发布于
2024年11月1日
许可协议