v1.0.0
發布於 2015 年 2 月 12 日 – 文字版本

TOML v0.4.0

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

作者：Tom Preston-Werner。

請注意，此規格仍在大量變動中。在標示為 1.0 之前，您應假設它是不穩定的，並採取相應措施。

目標

TOML 旨在成為一種極簡的設定檔格式，由於語意顯而易見，因此易於閱讀。TOML 設計為可以明確對應到雜湊表。TOML 應易於解析為各種語言中的資料結構。

規格

  • TOML 區分大小寫。
  • TOML 檔案必須只包含 UTF-8 編碼的 Unicode 字元。
  • 空白表示 Tab (0x09) 或空白 (0x20)。
  • 換行表示 LF (0x0A) 或 CRLF (0x0D0A)。

註解

使用井號符號表達您的想法。它們從符號延伸到該行的結尾。

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

字串

有四種表達字串的方式：基本、多行基本、文字和多行文字。所有字串都必須只包含有效的 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)
\\         - backslash       (U+005C)
\uXXXX     - unicode         (U+XXXX)
\UXXXXXXXX - unicode         (U+XXXXXXXX)

可以使用 \uXXXX 或 \UXXXXXXXX 形式跳脫任何 Unicode 字元。跳脫碼必須是有效的 Unicode 純量值。

所有未列於上方的其他跳脫序列均為保留字，如果使用，TOML 應產生錯誤。

有時您需要表達文字段落（例如翻譯檔案），或希望將非常長的字串分成多行。TOML 讓這變得容易。多行基本字串兩側各加上三個引號，並允許換行。緊接在開啟分隔符號後的換行符號將會被修剪。所有其他空白和換行字元保持不變。

key1 = """
Roses are red
Violets are blue"""

TOML 解析器應可自由地將換行符號標準化為對其平台有意義的任何內容。

# On a Unix system, the above multi-line string will most likely be the same as:
key2 = "Roses are red\nViolets are blue"

# On a Windows system, it will most likely be equivalent to:
key3 = "Roses are red\r\nViolets are blue"

若要撰寫長字串而不引入不必要的空白，請以 \ 結束一行。\ 將會與所有空白（包括換行符號）一起修剪，直到下一個非空白字元或關閉分隔符號。如果開啟分隔符號後的字元是反斜線和換行符號，則它們都將與所有空白和換行符號一起修剪，直到下一個非空白字元或關閉分隔符號。所有對基本字串有效的跳脫序列對多行基本字串也都有效。

# The following strings are byte-for-byte equivalent:
key1 = "The quick brown fox jumps over the lazy dog."

key2 = """
The quick brown \


  fox jumps over \
    the lazy dog."""

key3 = """\
       The quick brown \
       fox jumps over \
       the lazy dog.\
       """

可以使用任何 Unicode 字元，但必須跳脫下列字元：反斜線和控制字元（U+0000 至 U+001F）。引號不必跳脫，除非它們的存在會產生過早的關閉分隔符號。

如果您經常指定 Windows 路徑或正規表示式，則必須跳脫反斜線會很快變得繁瑣且容易出錯。為了提供協助，TOML 支援完全不允許跳脫的字面字串。字面字串由單引號包圍。與基本字串一樣，它們必須出現在單一行中

# What you see is what you get.
winpath  = 'C:\Users\nodejs\templates'
winpath2 = '\\ServerX\admin$\system32\'
quoted   = 'Tom "Dubs" Preston-Werner'
regex    = '<\i\c*\s*>'

由於沒有跳脫，因此無法在由單引號包圍的字面字串中撰寫單引號。幸運的是，TOML 支援解決此問題的多行字面字串版本。多行字面字串兩側各加上三個單引號，並允許換行。與字面字串一樣，完全沒有跳脫。緊接在開啟分隔符號後的換行符號將會被修剪。分隔符號之間的所有其他內容都會照樣解釋，不修改。

regex2 = '''I [dw]on't need \d{2} apples'''
lines  = '''
The first newline is
trimmed in raw strings.
   All other whitespace
   is preserved.
'''

對於二進制資料，建議您使用 Base64 或其他適當的 ASCII 或 UTF-8 編碼。該編碼的處理方式將取決於應用程式。

整數

整數是全數字。正數可以加上正號。負數可以加上負號。

+99
42
0
-17

對於大數字，您可以使用底線來增強可讀性。每個底線必須至少有一個數字圍繞。

1_000
5_349_221
1_2_3_4_5     # valid but inadvisable

不允許前導零。不允許十六進制、八進制和二進制形式。無法表示為一系列數字的值，例如「無限大」和「非數字」，也不允許。

預期 64 位元（有號長整數）範圍（-9,223,372,036,854,775,808 到 9,223,372,036,854,775,807）。

浮點數

浮點數包含一個整數部分（可以加上正號或負號），後面跟著一個小數部分和/或一個指數部分。如果小數部分和指數部分同時存在，小數部分必須在指數部分之前。

# fractional
+1.0
3.1415
-0.01

# exponent
5e+22
1e6
-2E-2

# both
6.626e-34

小數部分是小數點後接一個或多個數字。

指數部分是大寫或小寫的 E，後面接一個整數部分（可以加上正號或負號）。

與整數類似，您可以使用底線來增強可讀性。每個底線必須至少有一個數字圍繞。

9_224_617.445_991_228_313
1e1_000

預期 64 位元（雙精度）精度。

布林值

布林值只是您習慣的記號。始終是小寫。

true
false

日期時間

日期時間是 RFC 3339 日期。

1979-05-27T07:32:00Z
1979-05-27T00:32:00-07:00
1979-05-27T00:32:00.999999-07:00

陣列

陣列是方括號，裡面有其他基本類型。空格會被忽略。元素以逗號分隔。資料類型不能混合（儘管所有字串類型都應視為同類型）。

[ 1, 2, 3 ]
[ "red", "yellow", "green" ]
[ [ 1, 2 ], [3, 4, 5] ]
[ "all", 'strings', """are the same""", '''type'''] # this is ok
[ [ 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 是該表格的鍵值。鍵位於等號的左側，值位於右側。鍵名稱和值周圍的空格會被忽略。鍵、等號和值必須在同一行（儘管有些值可以斷行到多行）。

鍵可以是裸露的或帶引號的。裸露鍵只能包含字母、數字、底線和破折號（A-Za-z0-9_-）。帶引號鍵遵循與基本字串完全相同的規則，並允許您使用更廣泛的鍵名稱。最佳做法是只在絕對必要時使用裸露鍵。

表格中的鍵值對不保證以任何特定順序排列。

[table]
key = "value"
bare_key = "value"
bare-key = "value"

"127.0.0.1" = "value"
"character encoding" = "value"
"ʎǝʞ" = "value"

點在裸鍵中被禁止，因為點用於表示巢狀表格！每個點分隔部分的命名規則與鍵相同（見上文）。

[dog."tater.man"]
type = "pug"

在 JSON 領域，這將提供以下結構

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

點分隔部分周圍的空白會被忽略，但是，最佳實務是不使用任何多餘的空白。

[a.b.c]          # this is best practice
[ d.e.f ]        # same as [d.e.f]
[ g .  h  . i ]  # same as [g.h.i]
[ j . "ʞ" . l ]  # same as [j."ʞ".l]

如果您不想指定所有超級表格，您不需要這麼做。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

所有表格名稱和鍵都必須是非空的。

# NOT VALID TOML
[]
[a.]
[a..b]
[.b]
[.]
 = "no key name" # not allowed

內嵌表格

內嵌表格提供更簡潔的語法來表示表格。它們對於分組資料特別有用，否則分組資料可能很快會變得冗長。內嵌表格用大括號 { 和 } 括起來。在大括號內，可能會出現零個或多個以逗號分隔的鍵/值對。鍵/值對採用與標準表格中的鍵/值對相同的形式。允許所有值類型，包括內嵌表格。

內嵌表格旨在出現在單行上。大括號之間不允許換行，除非它們在值中有效。即便如此，強烈建議不要將內嵌表格分成多行。如果您發現自己被這種慾望所控制，這表示您應該使用標準表格。

name = { first = "Tom", last = "Preston-Werner" }
point = { x = 1, y = 2 }

上述內嵌表格與以下標準表格定義相同

[name]
first = "Tom"
last = "Preston-Werner"

[point]
x = 1
y = 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"

您也可以在適當的地方使用內聯表格

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

認真嗎？

是的。

但為什麼？

因為我們需要一個體面的人類可讀格式，可以明確地映射到雜湊表格，而 YAML 規範長達 80 頁，讓我抓狂。不，JSON 不算。您知道為什麼。

天啊，你說得對

是的。想幫忙嗎？發送拉取請求。或撰寫解析器。勇敢一點。

使用 TOML 的專案

  • Cargo - Rust 語言的套件管理員。
  • InfluxDB - 分散式時間序列資料庫。
  • Heka - Mozilla 的串流處理系統。
  • Hugo - Go 中的靜態網站產生器。

實作

如果您有實作，請發送拉取請求加入此清單。請在自述檔中註明您的解析器支援的提交 SHA1 或版本標籤。

驗證器

TOML 解碼器和編碼器的與語言無關測試套件

編輯器支援

編碼器

轉換器