TOML v1.0.0-rc.2

全称：Tom 的（语义）明显、（配置）最小化的语言。（Tom’s Obvious, Minimal Language）
作者：Tom Preston-Werner、Pradyun Gedam 等人。

宗旨

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

规格

  • TOML 是大小写敏感的。
  • TOML 文件必须是合法的 UTF-8 编码的 Unicode 文档。
  • 空白是指制表符（0x09）或空格（0x20）。
  • 换行是指 LF（0x0A）或 CRLF（0x0D0A）。

注释

井号（#）将该行余下的部分标记为注释，除非它在字符串中。

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

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

键值对

TOML 文档最基本的构成区块是键值对。

键名在等号的左边而值在右边。
键名和键值周围的空白会被忽略。
键、等号和值必须在同一行（不过有些值可以跨多行）。

  1. key = "value"

值必须是下述类型之一。

未指定值是非法的。

  1. key = # 非法

键值对后必须换行（或 EOF）。（例外见内联表）

  1. first = "Tom" last = "Preston-Werner" # 非法

键名

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

裸键只能包含 ASCII 字母，ASCII 数字，下划线和短横线（A-Za-z0-9_-）。
注意裸键允许仅由纯 ASCII 数字构成，例如 1234，但是是被理解为字符串的。

  1. key = "value"
  2. bare_key = "value"
  3. bare-key = "value"
  4. 1234 = "value"

引号键遵循与基本字符串或字面量字符串相同的规则并允许你使用更为广泛的键名。
除非明显必要，使用裸键方为最佳实践。

  1. "127.0.0.1" = "value"
  2. "character encoding" = "value"
  3. "ʎǝʞ" = "value"
  4. 'key2' = "value"
  5. 'quoted "value"' = "value"

裸键中不能为空，但空引号键是允许的（虽然不建议如此）。

  1. = "no key name"  # 非法
  2. "" = "blank"     # 合法但不鼓励
  3. '' = 'blank'     # 合法但不鼓励

点分隔键是一系列通过点相连的裸键或引号键。
这允许了你将相近属性放在一起：

  1. name = "Orange"
  2. physical.color = "orange"
  3. physical.shape = "round"
  4. site."google.com" = true

等价于 JSON 的如下结构：

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

点分隔符周围的空白会被忽略，不过，最佳实践是不要使用任何不必要的空白。

多次定义同一个键是不行的。

  1. # 不要这样做
  2. name = "Tom"
  3. name = "Pradyun"

注意，裸键和引号键是等效的：

  1. # 这将不起作用
  2. spelling = "favorite"
  3. "spelling" = "favourite"

只要一个键还没有被直接定义过，你就仍可以对它和它下属的键名赋值。

  1. # 这使“fruit”键作为表存在。
  2. fruit.apple.smooth = true
  4. # 所以接下来你可以像中这样对“fruit”表添加内容：
  5. fruit.orange = 2
  1. # 以下是非法的
  3. # 这将 fruit.apple 的值定义为一个整数。
  4. fruit.apple = 1
  6. # 但接下来这将 fruit.apple 像表一样对待了。
  7. # 整数不能变成表。
  8. fruit.apple.smooth = true

不鼓励跳跃式地定义点分隔键。

  1. # 合法但不鼓励
  3. apple.type = "水果"
  4. orange.type = "水果"
  6. apple.skin = "薄"
  7. orange.skin = "厚"
  9. apple.color = "红"
  10. orange.color = "橙"
  1. # 建议
  3. apple.type = "水果"
  4. apple.skin = "薄"
  5. apple.color = "红"
  7. orange.type = "水果"
  8. orange.skin = "厚"
  9. orange.color = "橙"

由于裸键只允许由 ASCII 整数组成，所以可能写出看起来像浮点数、但实际上是两部分的点分隔键。
除非你有充分的理由（基本不太会），否则不要这样做。

  1. 3.14159 = "派"

上面的 TOML 对应以下 JSON。

  1. { "3": { "14159": "派" } }

字符串

共有四种方式来表示字符串：基本字符串、多行基本字符串、字面量和多行字面量。
所有字符串都只能包含有效的 UTF-8 字符。

基本字符串由引号（"）包裹。
任何 Unicode 字符都可以使用，除了那些必须转义的：引号，反斜杠，以及除制表符外的控制字符（U+0000 至 U+0008，U+000A 至 U+001F，U+007F）。

  1. str = "我是一个字符串。\"你可以把我引起来\"。姓名\t乔斯\u00E9\n位置\t旧金山。"

为了方便，一些流行的字符有其简便转义写法。

  1. \b         - backspace       (U+0008)
  2. \t         - tab             (U+0009)
  3. \n         - linefeed        (U+000A)
  4. \f         - form feed       (U+000C)
  5. \r         - carriage return (U+000D)
  6. \"         - quote           (U+0022)
  7. \\         - backslash       (U+005C)
  8. \uXXXX     - unicode         (U+XXXX)
  9. \UXXXXXXXX - unicode         (U+XXXXXXXX)

任何 Unicode 字符都可以用 \uXXXX 或 \UXXXXXXXX 的形式来转义。
转义码必须是有效的 Unicode 标量值。

所有上面未列出的其它转义序列都是保留的，如果它们被使用了，TOML 将产生一个错误。

有时你需要表示一小篇文本（例如译文）或者想要对非常长的字符串进行折行。
TOML 对此进行了简化。

多行基本字符串由三个引号包裹，允许折行。
紧随开头引号的那个换行会被去除。
其它空白和换行会被原样保留。

  1. str1 = """
  2. Roses are red
  3. Violets are blue"""

TOML 解析器可以相对灵活地解析成对所在平台有效的换行字符。

  1. # 在 Unix 系统，上面的多行字符串可能等同于：
  2. str2 = "Roses are red\nViolets are blue"
  4. # 在 Windows 系统，它可能等价于：
  5. str3 = "Roses are red\r\nViolets are blue"

想书写长字符串却不想引入无关空白，可以用“行末反斜杠”。
当一行的最后一个非空白字符是反斜杠 \ 时，它会连同它后面的所有空白（包括换行）一起被去除，直到下一个非空白字符或结束引号为止。
所有对基本字符串有效的转义序列，对多行基本字符串也同样适用。

  1. # 下列字符串的每一个字节都完全相同：
  2. str1 = "The quick brown fox jumps over the lazy dog."
  4. str2 = """
  5. The quick brown \
  8.   fox jumps over \
  9.     the lazy dog."""
  11. str3 = """\
  12.        The quick brown \
  13.        fox jumps over \
  14.        the lazy dog.\
  15.        """

任何 Unicode 字符都可以使用，除了那些必须被转义的：反斜杠和除制表符、换行符、回车符外的控制字符（U+0000 至 U+0008，U+000B，U+000C，U+000E 至 U+001F，U+007F）。

你可以在多行基本字符串内的任何地方写一个引号或两个毗连的引号。
它们也可以写在紧邻界分符内的位置。

  1. str4 = """这有两个引号：""。够简单。"""
  2. # str5 = """这有两个引号："""。"""  # 非法
  3. str5 = """这有三个引号：""\"。"""
  4. str6 = """这有十五个引号：""\"""\"""\"""\"""\"。"""
  6. # "这，"她说，"只是个无意义的条款。"
  7. str7 = """"这，"她说，"只是个无意义的条款。""""

如果你常常要指定 Windows 路径或正则表达式，那么必须转义反斜杠就马上成为啰嗦而易错的了。
为了帮助搞定这点，TOML 支持字面量字符串，它完全不允许转义。

字面量字符串由单引号包裹。
类似于基本字符串，他们只能表现为单行：

  1. # 所见即所得。
  2. winpath  = 'C:\Users\nodejs\templates'
  3. winpath2 = '\\ServerX\admin$\system32\'
  4. quoted   = 'Tom "Dubs" Preston-Werner'
  5. regex    = '<\i\c*\s*>'

由于没有转义，无法在由单引号包裹的字面量字符串中写入单引号。
万幸，TOML 支持一种多行版本的字面量字符串来解决这个问题。

多行字面量字符串两侧各有三个单引号来包裹，允许换行。
类似于字面量字符串，无论任何转义都不存在。
紧随开始标记的那个换行会被剔除。
开始结束标记之间的所有其它内容会原样对待。

  1. regex2 = '''I [dw]on't need \d{2} apples'''
  2. lines  = '''
  3. 原始字符串中的
  4. 第一个换行被剔除了。
  5.    所有其它空白
  6.    都保留了。
  7. '''

你可以在多行字面量字符串中的任何位置写一个或两个单引号，但三个以上的单引号序列不可以。

  1. quot15 = '''这有十五个引号："""""""""""""""'''
  3. # apos15 = '''这有十五个撇号：''''''''''''''''''  # 非法
  4. apos15 = "这有十五个撇号：'''''''''''''''"
  6. # '那，'，她说，'仍然没有意义。'
  7. str = ''''那，'，她说，'仍然没有意义。''''

除制表符以外的所有控制字符都不允许出现在字面量字符串中。
因此，对于二进制数据，建议使用 Base64 或其它合适的 ASCII 或 UTF-8 编码。
对那些编码的处理方式，将交由应用程序自己来确定。

整数

整数是纯数字。
正数可以有加号前缀。
负数的前缀是减号。

  1. int1 = +99
  2. int2 = 42
  3. int3 = 0
  4. int4 = -17

对于大数，你可以在数字之间用下划线来增强可读性。
每个下划线两侧必须至少有一个数字。

  1. int5 = 1_000
  2. int6 = 5_349_221
  3. int7 = 53_49_221  # 印度编号系统分组
  4. int8 = 1_2_3_4_5  # 合法但不鼓励

前导零是不允许的。
整数值 -0 与 +0 是有效的，并等同于无前缀的零。

非负整数值也可以用十六进制、八进制或二进制来表示。
在这些格式中，+ 不被允许，而（前缀后的）前导零是允许的。
十六进制值大小写不敏感。
数字间的下划线是允许的（但不能存在于前缀和值之间）。

  1. # 带有 `0x` 前缀的十六进制
  2. hex1 = 0xDEADBEEF
  3. hex2 = 0xdeadbeef
  4. hex3 = 0xdead_beef
  6. # 带有 `0o` 前缀的八进制
  7. oct1 = 0o01234567
  8. oct2 = 0o755 # 对于表示 Unix 文件权限很有用
  10. # 带有 `0b` 前缀的二进制
  11. bin1 = 0b11010110

任意 64 位有符号整数（从 −2^63 到 2^63-1）应被接受并进行无损处理。如果不能无损表示整数，则必须报告错误。

浮点数

浮点数应当被实现为 IEEE 754 binary64 值。

一个浮点数由一个整数部分（遵从与十进制整数值相同的规则）后跟上一个小数部分和/或一个指数部分组成。
如果小数部分和指数部分兼有，那小数部分必须在指数部分前面。

  1. # 小数
  2. flt1 = +1.0
  3. flt2 = 3.1415
  4. flt3 = -0.01
  6. # 指数
  7. flt4 = 5e+22
  8. flt5 = 1e06
  9. flt6 = -2E-2
  11. # 都有
  12. flt7 = 6.626e-34

小数部分是一个小数点后跟一个或多个数字。

一个指数部分是一个 E（大小写均可）后跟一个整数部分（遵从与十进制整数值相同的规则，但可以包含前导零）。

如果使用小数点，则小数点左右两侧必须至少包含一位数字。

  1. # 无效浮点数
  2. invalid_float_1 = .7
  3. invalid_float_2 = 7.
  4. invalid_float_3 = 3.e+20

与整数相似，你可以使用下划线来增强可读性。
每个下划线必须被至少一个数字围绕。

  1. flt8 = 224_617.445_991_228

浮点数值 -0.0 与 +0.0 是有效的，并且应当遵从 IEEE 754。

特殊浮点值也能够表示。
它们是小写的。

  1. # 无穷大
  2. sf1 = inf  # 正无穷
  3. sf2 = +inf # 正无穷
  4. sf3 = -inf # 负无穷
  6. # 非数字
  7. sf4 = nan  # 实际上对应信号非数码还是静默非数码，取决于实现
  8. sf5 = +nan # 等同于 `nan`
  9. sf6 = -nan # 有效，实际码取决于实现

布尔值

布尔值就是你所惯用的那样。
要小写。

  1. bool1 = true
  2. bool2 = false

坐标日期时刻

要准确地表示世上的一个特定时间，你可以使用指定了时区偏移量的 RFC 3339 格式的日期时刻。

  1. odt1 = 1979-05-27T07:32:00Z
  2. odt2 = 1979-05-27T00:32:00-07:00
  3. odt3 = 1979-05-27T00:32:00.999999-07:00

出于可读性的目的，你可以用空格替代日期和时刻中间的 T（RFC 3339 的第 5.6 节中允许了这样做）。

  1. odt4 = 1979-05-27 07:32:00Z

要求毫秒精度。 小数秒的进一步精度取决于实现。
如果该值包含的精度超出了实现所能支持的精度，则超出精度的部分必须被截断，而不能四舍五入。

各地日期时刻

如果你省略了 RFC 3339 日期时刻中的时区偏移量，这表示该日期时刻的使用并不涉及时区偏移。
在没有其它信息的情况下，并不知道它究竟该被转化成世上的哪一刻。
如果仍被要求转化，那结果将取决于实现。

  1. ldt1 = 1979-05-27T07:32:00
  2. ldt2 = 1979-05-27T00:32:00.999999

要求毫秒精度。 小数秒的进一步精度取决于实现。
如果该值包含的精度超出了实现所能支持的精度，则超出精度的部分必须被截断，而不能四舍五入。

各地日期

如果你只写了 RFC 3339 日期时刻中的日期部分，那它表示一整天，同时也不涉及时区偏移。

  1. ld1 = 1979-05-27

各地时刻

如果你只写了 RFC 3339 日期时刻中的时刻部分，它将只表示一天之中的那个时刻，而与任何特定的日期无关、亦不涉及时区偏移。

  1. lt1 = 07:32:00
  2. lt2 = 00:32:00.999999

要求毫秒精度。 小数秒的进一步精度取决于实现。
如果该值包含的精度超出了实现所能支持的精度，则超出精度的部分必须被截断，而不能四舍五入。小数秒的精度取决于实现，但至少应当能够精确到毫秒。
如果它的值超出了实现所支持的精度，那多余的部分必须被舍弃，而不能四舍五入。

数组

数组是内含值的方括号。
空白会被忽略。
子元素由逗号分隔。
数组可以包含与键值对所允许的相同数据类型的值。
可以混合不同类型的值。

  1. integers = [ 1, 2, 3 ]
  2. colors = [ "红", "黄", "绿" ]
  3. nested_array_of_int = [ [ 1, 2 ], [3, 4, 5] ]
  4. nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
  5. string_array = [ "所有的", '字符串', """是相同的""", '''类型''' ]
  7. # 允许混合类型的数组
  8. numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
  9. contributors = [
  10.   "Foo Bar <foo@example.com>",
  11.   { name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" }
  12. ]

数组可以跨行。
数组的最后一个值后面可以有终逗号（也称为尾逗号）。
值和结束括号前可以存在任意数量的换行和注释。

  1. integers2 = [
  2.   1, 2, 3
  3. ]
  5. integers3 = [
  6.   1,
  7.   2, # 这是可以的
  8. ]

表

表（也被称为哈希表或字典）是键值对的集合。
它们在方括号里，并作为单独的行出现。
看得出它们不同于数组，因为数组只有值。

  1. [table]

在它下方，直至下一个表或文件结束，都是这个表的键值对。
表不保证保持键值对的指定顺序。

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

表名的规则与键名相同（见前文键名定义）。

  1. [dog."tater.man"]
  2. type.name = "pug"

等价于 JSON 的如下结构：

  1. { "dog": { "tater.man": { "type": { "name": "pug" } } } }

键名周围的空格会被忽略，然而最佳实践还是不要有任何多余的空白。

  1. [a.b.c]            # 这是最佳实践
  2. [ d.e.f ]          # 等同于 [d.e.f]
  3. [ g .  h  . i ]    # 等同于 [g.h.i]
  4. [ j . "ʞ" . 'l' ]  # 等同于 [j."ʞ".'l']

你不必层层完整地写出你不想写的所有途径的父表。
TOML 知道该怎么办。

  1. # [x] 你
  2. # [x.y] 不
  3. # [x.y.z] 需要这些
  4. [x.y.z.w] # 来让这生效
  6. [x] # 允许后置父表定义

空表是允许的，只要里面没有键值对就行了。

类似于键名，你不能重复定义任何表。
这样做是非法的。

  1. # 不要这样做
  3. [fruit]
  4. apple = "红"
  6. [fruit]
  7. orange = "橙"
  1. # 也不要这样做
  3. [fruit]
  4. apple = "红"
  6. [fruit.apple]
  7. texture = "光滑"

不鼓励无序地定义表。

  1. # 有效但不鼓励
  2. [fruit.apple]
  3. [animal]
  4. [fruit.orange]
  1. # 推荐
  2. [fruit.apple]
  3. [fruit.orange]
  4. [animal]

点分隔键将每个点左侧的任何东西定义为表。
由于表不能定义多于一次，不允许使用 [table] 头重定义这样的表。
同样地，使用点分隔键来重定义已经以 [table] 形式定义过的表也是不允许的。

不过，[table] 形式可以被用来定义通过点分隔键定义的表中的子表。

  1. [fruit]
  2. apple.color = "红"
  3. apple.taste.sweet = true
  5. # [fruit.apple]  # 非法
  6. # [fruit.apple.taste]  # 非法
  8. [fruit.apple.texture]  # 你可以添加子表
  9. smooth = true

内联表

内联表提供了一种更为紧凑的语法来表示表。
对于否则就很啰嗦的成组数据，这尤其有用。
内联表由花括号 { 和 } 包裹。
在括号中，可以出现零或更多个以逗号分隔的键值对。
键值对采取与标准表中的键值对相同的形式。
什么类型的值都可以，包括内联表。

内联表得出现在同一行内。
内联表中，最后一对键值对后不允许终逗号（也称为尾逗号）。
不允许花括号中出现任何换行，除非在值中它们合法。
即便如此，也强烈不建议把一个内联表搞成纵跨多行的样子。
如果你发现自己真的需要，那意味着你应该使用标准表。

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

上述内联表等同于下面的标准表定义：

  1. [name]
  2. first = "Tom"
  3. last = "Preston-Werner"
  5. [point]
  6. x = 1
  7. y = 2
  9. [animal]
  10. type.name = "pug"

内联表完全在内部定义键和子表。
新键和子表不再能被添加进去。

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

类似地，内联表不能被用来向一个已定义的表添加键或子表。

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

表数组

尚未描述的最后一种语法允许编写表数组。
这可以通过双方括号来表示。
在它下方，直至下一个表或文件结束，都是该表的键值对。
各个具有相同方括号名的表将会成为该表数组内的一员。
这些表按出现顺序插入。
一个没有任何键值对的双方括号表将被视为一个空表。

  1. [[products]]
  2. name = "Hammer"
  3. sku = 738594937
  5. [[products]]
  7. [[products]]
  8. name = "Nail"
  9. sku = 284758393
  11. color = "gray"

等价于 JSON 的如下结构。

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

你还可以创建一个嵌套表数组。
只需在子表上使用相同的双方括号语法即可。
在嵌套数组中，每个双方括号子表将隶属于最近定义的表元素。
普通的子表（非数组）同样也隶属于最近定义的表元素。

  1. [[fruit]]
  2.   name = "apple"
  4.   [fruit.physical]  # 子表
  5.     color = "red"
  6.     shape = "round"
  8.   [[fruit.variety]]  # 嵌套表数组
  9.     name = "red delicious"
  11.   [[fruit.variety]]
  12.     name = "granny smith"
  14. [[fruit]]
  15.   name = "banana"
  17.   [[fruit.variety]]
  18.     name = "plantain"

上述 TOML 等价于 JSON 的如下结构。

  1. {
  2.   "fruit": [
  3.     {
  4.       "name": "apple",
  5.       "physical": {
  6.         "color": "red",
  7.         "shape": "round"
  8.       },
  9.       "variety": [
  10.         { "name": "red delicious" },
  11.         { "name": "granny smith" }
  12.       ]
  13.     },
  14.     {
  15.       "name": "banana",
  16.       "variety": [
  17.         { "name": "plantain" }
  18.       ]
  19.     }
  20.   ]
  21. }

如果一个表或表数组的父级是一个数组元素，该元素必须在定义子级前先定义。
顺序颠倒的行为，必须在解析时报错。

  1. # 非法的 TOML 文档
  2. [fruit.physical]  # 子表，但它应该隶属于哪个父元素？
  3.   color = "red"
  4.   shape = "round"
  6. [[fruit]]  # 解析器必须在发现“fruit”是数组而非表时抛出错误
  7.   name = "apple"

若试图向一个静态定义的数组追加内容，即便数组尚且为空，也必须在解析时报错。

  1. # 非法的 TOML 文档
  2. fruit = []
  4. [[fruit]] # 不允许

若试图用已经确定为数组的名称定义表，必须在解析时报错。
将数组重定义为普通表的行为，也必须在解析时报错。

  1. # 非法的 TOML 文档
  2. [[fruit]]
  3.   name = "apple"
  5.   [[fruit.variety]]
  6.     name = "red delicious"
  8.   # 非法：该表与之前的表数组相冲突
  9.   [fruit.variety]
  10.     name = "granny smith"
  12.   [fruit.physical]
  13.     color = "red"
  14.     shape = "round"
  16.   # 非法：该表数组与之前的表相冲突
  17.   [[fruit.physical]]
  18.     color = "green"

你也可以适当使用内联表：

  1. points = [ { x = 1, y = 2, z = 3 },
  2.            { x = 7, y = 8, z = 9 },
  3.            { x = 2, y = 4, z = 8 } ]

文件扩展名

TOML 文件应当使用 .toml 扩展名。

MIME 类型

在互联网上传输 TOML 文件时，恰当的 MIME 类型是 application/toml。