v1.0.0
发布于 2013 年 3 月 17 日 – 文本版本

TOML v0.1.0

Tom's Obvious, Minimal Language。(Tom 的显而易见、极简语言)

作者:Tom Preston-Werner。

请注意,此规范仍在发生很多变化。在它被标记为 1.0 之前,您应该假设它是不稳定的,并相应地采取行动。

目标

TOML 旨在成为一种极简的配置文件格式,由于其明显的语义,易于阅读。TOML 设计为明确地映射到哈希表。TOML 应该很容易被解析成各种语言中的数据结构。

规范

  • TOML 区分大小写。
  • 空白字符是指制表符 (0x09) 或空格 (0x20)。

注释

用井号表达你的想法。它们从井号开始到行尾。

# I am a comment. Hear me roar. Roar.
key = "value" # Yeah, you can do this.

字符串

专业提示™:您可能会注意到此规范与 JSON 的字符串定义相同,除了 TOML 要求使用 UTF-8 编码。这是故意的。

字符串是由双引号括起来的一行值。字符串必须只包含有效的 UTF-8 字符。可以使用任何 Unicode 字符,除了必须转义的字符:双引号、反斜杠和控制字符 (U+0000 到 U+001F)。

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

为了方便起见,一些常用的字符有一个紧凑的转义序列。

\b     - backspace       (U+0008)
\t     - tab             (U+0009)
\n     - linefeed        (U+000A)
\f     - form feed       (U+000C)
\r     - carriage return (U+000D)
\"     - quote           (U+0022)
\/     - slash           (U+002F)
\\     - backslash       (U+005C)
\uXXXX - unicode         (U+XXXX)

任何 Unicode 字符都可以使用 \uXXXX 形式进行转义。

其他特殊字符是保留字符,如果使用,TOML 应该产生错误。这意味着 Windows 上的路径将始终必须使用双反斜杠。

wrong = "C:\Users\nodejs\templates" # note: doesn't produce a valid path
right = "C:\\Users\\nodejs\\templates"

对于二进制数据,建议您使用 Base 64 或其他合适的编码。该编码的处理方式将是特定于应用程序的。

整数

整数是单独的数字。感觉负面?做自然的事情。预期最小大小为 64 位。

42
-17

浮点数

浮点数是包含一个小数点的数字。小数点两侧必须至少有一个数字。预期精度为 64 位(双精度)。

3.1415
-0.01

布尔值

布尔值只是您习惯使用的标记。始终小写。

true
false

日期时间

日期时间是 ISO8601 日期,但只允许完整的世界时形式。

1979-05-27T07:32:00Z

数组

数组是用方括号括起来的包含其他基本类型的数组。忽略空白字符。元素用逗号分隔。不,您不能混合数据类型,那很蠢。

[ 1, 2, 3 ]
[ "red", "yellow", "green" ]
[ [ 1, 2 ], [3, 4, 5] ]
[ [ 1, 2 ], ["a", "b", "c"] ] # this is ok
[ 1, 2.0 ] # note: this is NOT ok

数组也可以是多行的。因此,除了忽略空白字符外,数组还忽略括号之间的新行。在结束括号之前允许使用结尾逗号。

key = [
  1, 2, 3
]

key = [
  1,
  2, # this is ok
]

哈希表

有两种方法可以创建键。我称它们为“键组”和“键”。两者都只是普通的键,但键组的值始终只有一个哈希表。

键组单独出现在一行上的方括号中。您可以将它们与数组区分开来,因为数组始终只是值。

[keygroup]

在键组下方,以及直到下一个键或文件结尾,都是该键组的键/值。键位于等号的左侧,值位于右侧。键从第一个非空白字符开始,到等号之前的最后一个非空白字符结束。键组中的键/值对是无序的。

[keygroup]
key = "value"

您可以根据需要缩进键及其值。制表符或空格。随意使用。你问为什么?因为你可以有嵌套的哈希表。啪。

嵌套的哈希表由包含点的键组表示。随意命名您的键组,只要不要使用点。点是保留字符。服从。

[key.tater]
type = "pug"

在 JSON 世界中,这将为您提供以下结构。

{ "key": { "tater": { "type": "pug" } } }

如果您不想指定所有超级键,则不必指定。TOML 知道如何为您完成。

# [x] you
# [x.y] don't
# [x.y.z] need these
[x.y.z.w] # for this to work

转换为哈希表时,空键组应导致键的值为空哈希表。

小心不要覆盖以前的键。那很蠢。并且应该产生错误。

# DO NOT WANT
[fruit]
type = "apple"

[fruit.type]
apple = "yes"

真的假的?

是的。

为什么?

因为我们需要一种体面的、人类可读的格式,该格式可以映射到哈希表,而 YAML 规范却长达 80 页,并且让我感到愤怒。不,JSON 不算数。你知道为什么。

哦天哪,你说得对

是的。想帮忙吗?发送一个拉取请求。或者编写一个解析器。要勇敢。

实现

如果您有实现,请发送一个拉取请求添加到此列表中。请在您的自述文件中注意您的解析器支持的提交 SHA1 或版本标签。

验证器

TOML 解析器的语言无关测试套件

编辑器支持

编码器