v1.0.0
发布于 2013 年 9 月 24 日 – 文本版本

TOML v0.2.0

Tom's Obvious, Minimal Language（汤姆的显而易见、极简语言）。

作者：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"

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

整数

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

42
-17

浮点数

浮点数是在其中包含单个点的数字。小数点两侧必须至少有一个数字。预期精度为 64 位（双精度）。

3.1415
-0.01

布尔值

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

true
false

日期时间

日期时间是 ISO 8601 日期，但只允许使用完整的 UTC 格式。

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
]

表

表（也称为哈希表或字典）是键/值对的集合。它们单独出现在一行上的方括号中。您可以将它们与数组区分开来，因为数组永远只是值。

[table]

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

[table]
key = "value"

您可以随意缩进键及其值。制表符或空格。尽情发挥吧。你问为什么？因为你可以有嵌套表。啪。

嵌套表由带有点的表名表示。随意命名你的表，但不要使用点。点是保留字符。服从。

[dog.tater]
type = "pug"

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

{ "dog": { "tater": { "type": "pug" } } }

如果您不想指定所有超级表，则无需指定。TOML 知道如何为您完成。

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

允许使用空表，它们只是没有键/值对。

只要超级表尚未直接定义且尚未定义特定键，您仍然可以写入它。

[a.b]
c = 1

[a]
d = 2

您不能多次定义任何键或表。这样做是无效的。

# DO NOT DO THIS

[a]
b = 1

[a]
c = 2
# DO NOT DO THIS EITHER

[a]
b = 1

[a.b]
c = 2

表数组

尚未表达的最后一种类型是表数组。这些可以通过使用双括号中的表名来表示。每个具有相同双括号名称的表都将是数组中的一个元素。表按遇到的顺序插入。没有键/值对的双括号表将被视为空表。

[[products]]
name = "Hammer"
sku = 738594937

[[products]]

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

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

{
  "products": [
    { "name": "Hammer", "sku": 738594937 },
    { },
    { "name": "Nail", "sku": 284758393, "color": "gray" }
  ]
}

您还可以创建嵌套的表数组。只需在子表上使用相同的双括号语法即可。每个双括号子表都将属于其上最近定义的表元素。

[[fruit]]
  name = "apple"

  [fruit.physical]
    color = "red"
    shape = "round"

  [[fruit.variety]]
    name = "red delicious"

  [[fruit.variety]]
    name = "granny smith"

[[fruit]]
  name = "banana"

  [[fruit.variety]]
    name = "plantain"

以上 TOML 映射到以下 JSON。

{
  "fruit": [
    {
      "name": "apple",
      "physical": {
        "color": "red",
        "shape": "round"
      },
      "variety": [
        { "name": "red delicious" },
        { "name": "granny smith" }
      ]
    },
    {
      "name": "banana",
      "variety": [
        { "name": "plantain" }
      ]
    }
  ]
}

尝试使用与已建立数组相同的名称定义普通表必须在解析时产生错误。

# INVALID TOML DOC
[[fruit]]
  name = "apple"

  [[fruit.variety]]
    name = "red delicious"

  # This table conflicts with the previous table
  [fruit.variety]
    name = "granny smith"

真的假的？

是的。

为什么？

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

哦天哪，你说得对

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

实现

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

验证器

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

编辑器支持

编码器