TOML v1.0.0
Tom 的顯而易見、極簡語言。
由 Tom Preston-Werner、Pradyun Gedam 等人編寫。
目標
TOML 的目標是成為一個極簡的設定檔格式，由於其顯而易見的語意而易於閱讀。TOML 的設計目的是明確地對應到一個雜湊表。TOML 應易於解析成各種語言的資料結構。
規格
- TOML 區分大小寫。
- TOML 檔案必須是有效的 UTF-8 編碼 Unicode 文件。
- 空白表示 tab (0x09) 或空白 (0x20)。
- 換行表示 LF (0x0A) 或 CRLF (0x0D 0x0A)。
註解
井號符號將該行剩餘部分標記為註解，除非在字串內。
# This is a full-line comment
key = "value" # This is a comment at the end of a line
another = "# This is not a comment"註解中不允許 tab 以外的控制字元（U+0000 至 U+0008、U+000A 至 U+001F、U+007F）。
金鑰/值對
TOML 文件的主要建構區塊是金鑰/值對。
金鑰位於等號符號的左側，值位於右側。金鑰名稱和值周圍的空白會被忽略。金鑰、等號符號和值必須在同一行（儘管有些值可以斷行到多行）。
key = "value"值必須具有下列其中一種類型。
未指定的值無效。
key = # INVALID金鑰/值對之後必須有換行（或 EOF）。（有關例外，請參閱 內嵌表格。）
first = "Tom" last = "Preston-Werner" # INVALID金鑰
金鑰可以是未加引號、加引號或點分。
未加引號的金鑰只能包含 ASCII 字母、ASCII 數字、底線和連字元（A-Za-z0-9_-）。請注意，未加引號的金鑰允許只由 ASCII 數字組成，例如 1234，但總是會被解釋為字串。
key = "value"
bare_key = "value"
bare-key = "value"
1234 = "value"加引號的金鑰遵循與基本字串或字面字串完全相同的規則，並允許您使用更廣泛的金鑰名稱。最佳做法是在絕對必要時才使用未加引號的金鑰。
"127.0.0.1" = "value"
"character encoding" = "value"
"ʎǝʞ" = "value"
'key2' = "value"
'quoted "value"' = "value"未加引號的金鑰不能為空，但允許加引號的金鑰為空（儘管不建議）。
= "no key name" # INVALID
"" = "blank" # VALID but discouraged
'' = 'blank' # VALID but discouraged點綴鍵是一系列的裸鍵或帶引號的鍵，用點號連接。這允許將相似的屬性分組在一起
name = "Orange"
physical.color = "orange"
physical.shape = "round"
site."google.com" = true在 JSON 領域中，這將提供以下結構
{
"name": "Orange",
"physical": {
"color": "orange",
"shape": "round"
},
"site": {
"google.com": true
}
}有關點綴鍵定義的表格的詳細資訊，請參閱以下 表格 區段。
忽略以點號分隔的部分周圍的空白。但是，最佳做法是不使用任何多餘的空白。
fruit.name = "banana" # this is best practice
fruit. color = "yellow" # same as fruit.color
fruit . flavor = "banana" # same as fruit.flavor縮排被視為空白並被忽略。
多次定義鍵是無效的。
# DO NOT DO THIS
name = "Tom"
name = "Pradyun"請注意，裸鍵和帶引號的鍵是等效的
# THIS WILL NOT WORK
spelling = "favorite"
"spelling" = "favourite"只要鍵尚未直接定義，您仍可以寫入鍵和鍵中的名稱。
# This makes the key "fruit" into a table.
fruit.apple.smooth = true
# So then you can add to the table "fruit" like so:
fruit.orange = 2# THE FOLLOWING IS INVALID
# This defines the value of fruit.apple to be an integer.
fruit.apple = 1
# But then this treats fruit.apple like it's a table.
# You can't turn an integer into a table.
fruit.apple.smooth = true不建議以不按順序的方式定義點綴鍵。
# VALID BUT DISCOURAGED
apple.type = "fruit"
orange.type = "fruit"
apple.skin = "thin"
orange.skin = "thick"
apple.color = "red"
orange.color = "orange"# RECOMMENDED
apple.type = "fruit"
apple.skin = "thin"
apple.color = "red"
orange.type = "fruit"
orange.skin = "thick"
orange.color = "orange"由於裸鍵只能由 ASCII 整數組成，因此可以寫出看起來像浮點數但實際上是 2 部分點綴鍵的點綴鍵。除非您有充分的理由（您可能沒有），否則請不要這樣做。
3.14159 = "pi"上述 TOML 對應到以下 JSON。
{ "3": { "14159": "pi" } }字串
有四種表達字串的方式：基本、多行基本、文字和多行文字。所有字串都必須只包含有效的 UTF-8 字元。
基本字串以引號 (") 包圍。可以使用任何 Unicode 字元，但必須跳脫的字元除外：引號、反斜線以及除了 tab (U+0000 至 U+0008、U+000A 至 U+001F、U+007F) 之外的控制字元。
str = "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 讓這變得容易。
多行基本字串兩側各以三個引號包圍，並允許換行。緊接在開啟分隔符號之後的換行將會被修剪。所有其他空白和換行字元保持不變。
str1 = """
Roses are red
Violets are blue"""TOML 解析器應隨時調整換行，使其對其平台有意義。
# On a Unix system, the above multi-line string will most likely be the same as:
str2 = "Roses are red\nViolets are blue"
# On a Windows system, it will most likely be equivalent to:
str3 = "Roses are red\r\nViolets are blue"若要撰寫長字串而不引入不必要的空白，請使用「換行反斜線」。當行中最後一個非空白字元為未跳脫的 \ 時，它會連同所有空白（包括換行）修剪至下一個非空白字元或封閉分隔符號。所有適用於基本字串的跳脫序列也適用於多行基本字串。
# The following strings are byte-for-byte equivalent:
str1 = "The quick brown fox jumps over the lazy dog."
str2 = """
The quick brown \
fox jumps over \
the lazy dog."""
str3 = """\
The quick brown \
fox jumps over \
the lazy dog.\
"""可以使用任何 Unicode 字元，但必須跳脫以下字元：反斜線和控制字元（標籤、換行和回車除外）（U+0000 至 U+0008、U+000B、U+000C、U+000E 至 U+001F、U+007F）。
可以在多行基本字串中的任何位置撰寫引號或兩個相鄰的引號。它們也可以寫在分隔符號內。
str4 = """Here are two quotation marks: "". Simple enough."""
# str5 = """Here are three quotation marks: """.""" # INVALID
str5 = """Here are three quotation marks: ""\"."""
str6 = """Here are fifteen quotation marks: ""\"""\"""\"""\"""\"."""
# "This," she said, "is just a pointless statement."
str7 = """"This," she said, "is just a pointless statement.""""如果您經常指定 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.
'''您可以在多行字面字串中的任何位置撰寫 1 或 2 個單引號，但禁止出現三個或更多個單引號的序列。
quot15 = '''Here are fifteen quotation marks: """""""""""""""'''
# apos15 = '''Here are fifteen apostrophes: '''''''''''''''''' # INVALID
apos15 = "Here are fifteen apostrophes: '''''''''''''''"
# 'That,' she said, 'is still pointless.'
str = ''''That,' she said, 'is still pointless.''''字面字串中不允許標籤以外的控制字元。因此，對於二進位資料，建議您使用 Base64 或其他適當的 ASCII 或 UTF-8 編碼。該編碼的處理方式將取決於應用程式。
整數
整數是整數。正數前面可以加上正號。負數前面加上負號。
int1 = +99
int2 = 42
int3 = 0
int4 = -17對於大數字，您可以在數字之間使用底線來增強可讀性。每個底線兩側都必須至少有一個數字。
int5 = 1_000
int6 = 5_349_221
int7 = 53_49_221 # Indian number system grouping
int8 = 1_2_3_4_5 # VALID but discouraged不允許前導零。整數值 -0 和 +0 有效，且與未加前綴的零相同。
非負整數值也可以用十六進位、八進位或二進位表示。在這些格式中，不允許前導 +，但允許前導零（在字首之後）。十六進位值不分大小寫。數字之間允許使用底線（但字首和值之間不允許）。
# hexadecimal with prefix `0x`
hex1 = 0xDEADBEEF
hex2 = 0xdeadbeef
hex3 = 0xdead_beef
# octal with prefix `0o`
oct1 = 0o01234567
oct2 = 0o755 # useful for Unix file permissions
# binary with prefix `0b`
bin1 = 0b11010110應接受並無損失地處理任意 64 位元有號整數（從 −2^63 到 2^63−1）。如果無法無損失地表示整數，則必須擲回錯誤。
浮點數
浮點數應實作為 IEEE 754 binary64 值。
浮點數包含整數部分（遵循與十進位整數值相同的規則），後接小數部分和/或指數部分。如果同時存在小數部分和指數部分，小數部分必須在指數部分之前。
# fractional
flt1 = +1.0
flt2 = 3.1415
flt3 = -0.01
# exponent
flt4 = 5e+22
flt5 = 1e06
flt6 = -2E-2
# both
flt7 = 6.626e-34小數部分是小數點後接一個或多個數字。
指數部分是大寫或小寫的 E，後接整數部分（遵循與十進位整數值相同的規則，但可能包含前導零）。
如果使用小數點，則其兩側必須至少各有一個數字。
# INVALID FLOATS
invalid_float_1 = .7
invalid_float_2 = 7.
invalid_float_3 = 3.e+20與整數類似，您可以使用底線來增強可讀性。每個底線必須至少有一個數字。
flt8 = 224_617.445_991_228浮點數值 -0.0 和 +0.0 有效，且應根據 IEEE 754 進行對應。
也可以表達特殊浮點數值。它們永遠是小寫。
# infinity
sf1 = inf # positive infinity
sf2 = +inf # positive infinity
sf3 = -inf # negative infinity
# not a number
sf4 = nan # actual sNaN/qNaN encoding is implementation-specific
sf5 = +nan # same as `nan`
sf6 = -nan # valid, actual encoding is implementation-specific布林值
布林值就是您習慣的標記。永遠是小寫。
bool1 = true
bool2 = false偏移日期時間
若要明確表示時間中的特定時刻，您可以使用 RFC 3339 格式化的日期時間加上偏移量。
odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
odt3 = 1979-05-27T00:32:00.999999-07:00為了可讀性，您可以用空格字元取代日期和時間之間的 T 分隔符號（如 RFC 3339 第 5.6 節所允許）。
odt4 = 1979-05-27 07:32:00Z需要毫秒精度。小數秒的進一步精度取決於實作。如果值包含比實作所能支援更高的精度，則必須截斷額外的精度，而不是四捨五入。
當地日期時間
如果您從 RFC 3339 格式化的日期時間中省略偏移量，它將表示給定的日期時間，而與偏移量或時區無關。在沒有其他資訊的情況下，它無法轉換為時間中的瞬間。如果需要，轉換為瞬間取決於實作。
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999需要毫秒精度。小數秒的進一步精度取決於實作。如果值包含比實作所能支援更高的精度，則必須截斷額外的精度，而不是四捨五入。
當地日期
如果您僅包含 RFC 3339 格式化日期時間的日期部分，它將表示整個日期，而與偏移量或時區無關。
ld1 = 1979-05-27當地時間
如果您僅包含 RFC 3339 格式化日期時間的時間部分，它將表示那一天的時間，而與特定日期或任何偏移量或時區無關。
lt1 = 07:32:00
lt2 = 00:32:00.999999需要毫秒精度。小數秒的進一步精度取決於實作。如果值包含比實作所能支援更高的精度，則必須截斷額外的精度，而不是四捨五入。
陣列
陣列是方括號，裡面有值。忽略空白。元素以逗號分隔。陣列可以包含與鍵值對中允許的相同資料類型值。可以混合不同類型的值。
integers = [ 1, 2, 3 ]
colors = [ "red", "yellow", "green" ]
nested_arrays_of_ints = [ [ 1, 2 ], [3, 4, 5] ]
nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
string_array = [ "all", 'strings', """are the same""", '''type''' ]
# Mixed-type arrays are allowed
numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
contributors = [
"Foo Bar <foo@example.com>",
{ name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" }
]陣列可以跨越多行。陣列最後一個值之後允許有終止逗號（也稱為尾隨逗號）。任何數量的換行和註解可以出現在值、逗號和閉合括號之前。陣列值和逗號之間的縮排會被視為空白並忽略。
integers2 = [
1, 2, 3
]
integers3 = [
1,
2, # this is ok
]表格
表格（也稱為雜湊表或字典）是鍵值對的集合。它們由標題定義，標題本身位於一行中並帶有方括號。你可以區分標題和陣列，因為陣列永遠只會是值。
[table]在標題下方，直到下一個標題或檔案結束，都是該表格的鍵值。表格中的鍵值對並非保證會以任何特定順序排列。
[table-1]
key1 = "some string"
key2 = 123
[table-2]
key1 = "another string"
key2 = 456表格的命名規則與鍵相同（請參閱上方 鍵 的定義）。
[dog."tater.man"]
type.name = "pug"在 JSON 領域中，這將提供以下結構
{ "dog": { "tater.man": { "type": { "name": "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
[x] # defining a super-table afterward is ok允許空表格，其中沒有鍵值對。
與鍵一樣，你無法多次定義表格。這樣做是無效的。
# DO NOT DO THIS
[fruit]
apple = "red"
[fruit]
orange = "orange"# DO NOT DO THIS EITHER
[fruit]
apple = "red"
[fruit.apple]
texture = "smooth"不建議無序定義表格。
# VALID BUT DISCOURAGED
[fruit.apple]
[animal]
[fruit.orange]# RECOMMENDED
[fruit.apple]
[fruit.orange]
[animal]頂層表格，也稱為根表格，從文件開頭開始，並在第一個表格標題（或檔案結束）之前結束。與其他表格不同，它是無名的，且無法重新定位。
# Top-level table begins.
name = "Fido"
breed = "pug"
# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04點分隔鍵會為最後一個鍵部分之前的每個鍵部分建立和定義一個表格，前提是這些表格之前未建立。
fruit.apple.color = "red"
# Defines a table named fruit
# Defines a table named fruit.apple
fruit.apple.taste.sweet = true
# Defines a table named fruit.apple.taste
# fruit and fruit.apple were already created由於無法多次定義表格，因此不允許使用 [table] 標題重新定義這些表格。同樣地，不允許使用點分隔鍵重新定義已在 [table] 形式中定義的表格。但是， [table] 形式可以用於定義透過點分隔鍵定義的表格中的子表格。
[fruit]
apple.color = "red"
apple.taste.sweet = true
# [fruit.apple] # INVALID
# [fruit.apple.taste] # INVALID
[fruit.apple.texture] # you can add sub-tables
smooth = true內嵌表格
內嵌表格提供更簡潔的語法來表示表格。它們對於群組資料特別有用，否則群組資料可能會很快變得冗長。內嵌表格完全定義在花括號內：{ 和 }。在花括號內，可以出現零個或多個以逗號分隔的鍵值對。鍵值對採用與標準表格中的鍵值對相同的形式。允許所有值類型，包括內嵌表格。
內嵌表格旨在顯示在單一行上。內嵌表格中最後一組 key/value 之後不允許有終止逗號（也稱為尾隨逗號）。大括號之間不允許有換行符，除非它們在值中有效。即便如此，強烈建議不要將內嵌表格拆成多行。如果您發現自己有這種慾望，表示您應該使用標準表格。
name = { first = "Tom", last = "Preston-Werner" }
point = { x = 1, y = 2 }
animal = { type.name = "pug" }上述內嵌表格與下列標準表格定義相同
[name]
first = "Tom"
last = "Preston-Werner"
[point]
x = 1
y = 2
[animal]
type.name = "pug"內嵌表格完全自給自足，並定義它們內的所有鍵和子表格。無法在大括號外新增鍵和子表格。
[product]
type = { name = "Nail" }
# type.edible = false # INVALID同樣地，內嵌表格無法用於向已定義的表格新增鍵或子表格。
[product]
type.name = "Nail"
# type = { edible = false } # INVALID表格陣列
尚未描述的最後一個語法允許撰寫表格陣列。這些陣列可以使用帶有雙括號名稱的標頭來表示。該標頭的第一個實例定義陣列及其第一個表格元素，而每個後續實例都會在該陣列中建立並定義一個新的表格元素。表格會按照遇到的順序插入到陣列中。
[[products]]
name = "Hammer"
sku = 738594937
[[products]] # empty table within the array
[[products]]
name = "Nail"
sku = 284758393
color = "gray"在 JSON 領域中，這會提供下列結構。
{
"products": [
{ "name": "Hammer", "sku": 738594937 },
{ },
{ "name": "Nail", "sku": 284758393, "color": "gray" }
]
}任何對表格陣列的參照都會指向陣列中最近定義的表格元素。這允許您在最近的表格中定義子表格，甚至表格的子陣列。
[[fruits]]
name = "apple"
[fruits.physical] # subtable
color = "red"
shape = "round"
[[fruits.varieties]] # nested array of tables
name = "red delicious"
[[fruits.varieties]]
name = "granny smith"
[[fruits]]
name = "banana"
[[fruits.varieties]]
name = "plantain"上述 TOML 對應到以下 JSON。
{
"fruits": [
{
"name": "apple",
"physical": {
"color": "red",
"shape": "round"
},
"varieties": [
{ "name": "red delicious" },
{ "name": "granny smith" }
]
},
{
"name": "banana",
"varieties": [
{ "name": "plantain" }
]
}
]
}如果表格或表格陣列的父代是陣列元素，則該元素必須在定義子代之前已經定義。嘗試反轉該順序必須在解析時產生錯誤。
# INVALID TOML DOC
[fruit.physical] # subtable, but to which parent element should it belong?
color = "red"
shape = "round"
[[fruit]] # parser must throw an error upon discovering that "fruit" is
# an array rather than a table
name = "apple"嘗試附加到靜態定義的陣列，即使該陣列為空，也必須在解析時產生錯誤。
# INVALID TOML DOC
fruits = []
[[fruits]] # Not allowed嘗試使用與已建立陣列相同的名稱定義常規表格，必須在解析時產生錯誤。嘗試將常規表格重新定義為陣列也必須產生解析時錯誤。
# INVALID TOML DOC
[[fruits]]
name = "apple"
[[fruits.varieties]]
name = "red delicious"
# INVALID: This table conflicts with the previous array of tables
[fruits.varieties]
name = "granny smith"
[fruits.physical]
color = "red"
shape = "round"
# INVALID: This array of tables conflicts with the previous table
[[fruits.physical]]
color = "green"您也可以在適當的地方使用內嵌表格
points = [ { x = 1, y = 2, z = 3 },
{ x = 7, y = 8, z = 9 },
{ x = 2, y = 4, z = 8 } ]檔案名稱副檔名
TOML 檔案應使用副檔名 .toml。
MIME 類型
透過網際網路傳輸 TOML 檔案時，適當的 MIME 類型為 application/toml。
ABNF 語法
TOML 語法的正式說明可用，作為一個單獨的 ABNF 檔案。