v1.0.0
發布於 2013 年 9 月 24 日 – 文字版本

TOML v0.2.0

Tom 的顯而易見、極簡語言。

作者：Tom Preston-Werner。

請注意，此規格仍有許多變動。在標示為 1.0 之前，您應假設此規格不穩定，並採取相應措施。

目標

TOML 的目標是成為極簡的設定檔格式，由於語意明顯，因此易於閱讀。TOML 的設計目的是明確地對應到雜湊表。TOML 應易於解析成各種語言的資料結構。

規格

  • TOML 區分大小寫。
  • 空白表示 tab (0x09) 或空白 (0x20)。

註解

使用井號符號表達您的意見。井號符號從符號開始到該行的結尾。

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

字串

ProTip™：您可能會注意到，此規格與 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 日期，但只允許完整的祖魯格式。

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]

在表格下方，直到下一個表格或 EOF 都是該表格的鍵/值。鍵位於等號符號的左側，值位於右側。鍵從第一個非空白字元開始，並在等號符號之前的最後一個非空白字元結束。表格中的鍵/值對是無序的。

[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 解析器的與語言無關的測試套件

編輯器支援

編碼器