TOML 格式化工具

格式化並校驗 TOML(Tom's Obvious, Minimal Language)。整齊對齊 key = value、表格與陣列,並以行號提示語法錯誤。

TOML 的主要資料型別

型別 示例寫法 說明
字串(基本) "hello" 用雙引號括起來,支援 \n、\t 等轉義序列。
字串(字面量) 'C:\path' 用單引號括起來,完全不進行轉義處理,適合包含反斜槓的路徑字串。
整數 42 預設十進位制,也支援 0x(十六進位制)・0o(八進位制)・0b(二進位制),以及 1_000 這樣的下劃線分隔。
浮點數 3.14 指數記法(1e10)以及 inf・nan 也是有效值。
布林值 true true 或 false 二選一,首字母大寫(True)無效。
陣列 [1, 2, 3] 在方括號內用逗號分隔多個值,允許末尾逗號。
表格 [server] 表頭之後出現的所有 key = value 都屬於該表格的子項。
表格陣列 [[fruits-basket]] 通過重複同名表格來表示陣列(例如多個依賴包的定義)。
日期/時間 1979-05-27T07:32:00Z RFC 3339 格式,是唯一可以不加引號書寫的複合型別值。

使用技巧

  • 內聯陣列和內聯表僅支援寫在一行內的形式。如果陣列跨越多行,請先合併為一行再貼上。
  • 格式化結果會將「=」兩側統一為一個半形空格,並將陣列/內聯表的分隔符統一為「, 」,從而消除不同書寫者之間的格式差異。
  • 註釋(# 之後的內容)會被保留,唯一的改動是在「#」之後缺少空格時補上一個空格,改動幅度很小。
  • 連續的空行會被合併為一行輸出,讓各個表格之間的分界更容易辨認。
  • 本工具的所有處理都在瀏覽器內完成,您貼上的配置內容不會被發送到任何伺服器。

常見問題

如果內容以簡單的鍵值對為主,且由多人共同編輯(如依賴關係定義),TOML 更合適,因為縮排失誤很少會破壞結構。如果需要深層巢狀或在一個檔案中組合多份文件,YAML 的表現力更強。

本工具會正確格式化每一個 [[section]] 表頭,但不會像完整的 TOML→JSON 轉換器那樣,把同名的多個表格合併成一個數組物件。對於複雜的表格陣列結構,建議直接檢視逐行格式化後的結果來確認。

本工具會按 RFC 3339 語法識別並原樣輸出該值,但不會校驗其在日曆上是否真實存在(例如「2 月 30 日」這樣的非法日期)。如需嚴格的日期校驗,請另行確認。

目前尚不支援 """..."""'''...''',對應的行會被判定為錯誤。如需處理長文本,請先轉換為可寫在一行內的跳脫字元串格式。

不會。所有格式化處理都在您的瀏覽器內通過 JavaScript 完成,不會發送到伺服器或被儲存,因此即使配置檔案中包含憑據資訊也可以放心使用。
ツールくん

閒話 ― TOML 為何成為配置檔案的「通用語言」

TOML 由 GitHub 聯合創始人 Tom Preston-Werner 於 2013 年提出,其全稱「Tom's Obvious, Minimal Language」直接體現了設計理念:既要像 JSON 一樣便於機器解析,也要讓人類可以毫無歧義地直接閱讀和書寫。

真正讓 TOML 普及開來的關鍵,是 Rust 的包管理器 Cargo 採用 Cargo.toml 作為其配置檔案格式。此後,Python 的 PEP 518 又引入了 pyproject.toml 作為打包標準,將此前 setup.py、setup.cfg、requirements.txt 各自為政的局面統一了起來。

TOML 與 YAML 最大的區別在於「不賦予縮排任何意義」。YAML 中細微的縮排偏差很容易導致語法錯誤或資料結構被誤解析,而 TOML 僅通過 [section]key = value 的組合來表達層級,因此複製貼上導致的失誤相對更少。

不過 TOML 的表現力也因此略遜於 YAML:它沒有用於複用數值的錨點/別名機制,書寫深層巢狀結構也偏繁瑣,實際工作中往往需要根據資料結構在 TOML、YAML、JSON 之間做出取捨。