為什么 TOML 存在：Cargo.toml 和 pyproject.toml 背後的設計目標

一個儲存庫中的三種配置格式 - JSON 用於編輯器，YAML 用於 CI，TOML 用於構建，以及為什麼存在第三種格式的問題

儲存庫可以將 JSON、YAML 和 TOML 用於不同的配置表面。 ToolAcre 無法解釋每個項目的選擇，但轉換使結構差異具體化：TOML 作為根表開始，使用標頭和點路徑進行嵌套，並攜帶 JSON 中不可用的時間值。

載入範例而不是從外觀上爭論。當值輸入 JSON 時，巢狀表變成對象，雙括號表變成數組，註解消失。這些觀察到的邊界比一種語法本質上更好的通用宣告更具可操作性。

設計目標 — 最小、明顯的語意、易於閱讀、明確對應到雜湊表的格式

附帶的解析器公開了明顯的表語義：標頭是路徑，分配屬於活動表，並標量標記已定義 TOML 類型。字串不會僅僅因為其內容看起來像日期而被鍵入。實際的時間語法產生 ToolAcre 有意標準化的日期物件。

儲存庫不提供格式的創建者、日期或陳述的哲學，因此本文避免將記住的歷史呈現為事實。它報告在 smol-toml 和轉換器自己的標準化層中測試的行為。

附帶的解析器中可觀察到的設計屬性，沒有被動來源宣告

TOML 沒有 null，其文件根不能是陣列或標量。它在此映射中不提供 YAML 樣式的錨點或別名。註解存在於編寫的 TOML 中，但不被值解析器保留，因此無法透過 JSON 或 YAML 進行轉換。

不含引號的裸值遵循 TOML 語法，而不是 YAML 的架構選擇。解析器要么接受鍵入的值，要么報告無效的 TOML 以及位置資訊。 ToolAcre 不會為格式錯誤的賦值添加隱式字串模式。

支援的價值模型排除或處理不同的內容

此模型包括字串、有符號整數、浮點數、布林值、四種時間類型、陣列和表。表數組表示重複的物件記錄。超出 2^53 的大有符號整數在轉換時會變成十進位字串，因此 JavaScript 不會默默地對它們進行舍入。

時間值成為偏移日期時間、本地日期時間、本地日期或本地時間的以來源為導向的文字。此警告保留散文形式的類型，但 JSON 僅接收一個字串。因此，轉換回來會引用它並遺失本機 TOML 類型。

採用 — Rust 早期的 Cargo，PEP 518 選擇 pyproject.toml，以及 2021 中的 1.0.0 規範

Cargo 和 pyproject 採用是歷史和生態系統宣告，需要轉換器儲存庫中不存在的來源。這裡故意省略了它們。路徑或檔案名並不是時間順序、規範發布或標準決策的證據。

操作問題是目標工具是否讀取 TOML 以及它需要哪些表。檢查該工具的目前檔案。語法轉換器知道語法和值映射，而不是套件管理器配置契約。

生態系採用歷史在沒有儲存庫來源的情況下被省略

深度巢狀可能更難掃描，因為表格上下文會跨行持續存在，而大型表數組將一個邏輯列表分佈在重複的標頭中。 JSON 讓完整的層級結構明確，但卻加入了大括號和引號。這兩種表示都不會消除底層配置的複雜性。

解析器將嵌套在 100 處並將來源長度限制為 200 萬個字元。這些是拒絕邊界，而不是關於理想配置大小或通用 TOML 限制的宣告。

這不包括什麼 - TOML 每種語言中的解析器選擇，以及某些標準庫實現的唯讀性質

每種語言中的解析器選擇超出了範圍，標準庫寫入功能也是如此。 ToolAcre 動態使用 smol-toml 並包裝其錯誤。另一種實作可以以不同的方式格式化有效輸出，或在表示相同資料時公開另一個 API。

當互通性很重要時，對時間值、大整數、陣列和點鍵使用交叉工具夾具。此處接受的檔案不會自動被每個 TOML 使用者接受。

重點：TOML 認為是一種配置格式 - 以及語法轉換器面板如何讓您查看該形狀的任何 JSON 或 YAML 檔案

TOML 以可觀察的方式固執己見：表根、明確類型化值、本機時間類型和無 null。轉換暴露了這些選擇及其與 JSON 形目標的不相容性，而無需起源神話。

使用面板檢查樹木並識別警告。然後返回到目標的模式並編寫人類將維護的表格佈局。轉換器提供有關值的證據，而不是對格式偏好的判斷。

當 TOML 只是中間視圖時，同樣適用。在判斷可讀性之前，保留來源、比較標準化值並記錄每個時間或寬整數轉換。緊湊的表佈局仍然可以隱藏更改的類型，而詳細的表數組在語義上可以是準確的。格式選擇應遵循配置合約和維護工作流程，而不是產生的範例的視覺整潔度。