開發者工具·語法轉換器
TOML 表如何成為 JSON 物件：[table]、[[array]] 和點鍵
· 工作原理
toml json 資料格式
TOML 的標头看起來與 JSON 的大括号完全不同，但它们定义了完全相同的嵌套。這篇文章解釋了 [server]、[[products]] 和 a.b.c 如何映射到 JSON 物件和數組，以及這兩個模型的分歧點。
嵌套從哪裡來？ — 一個扁平化的 TOML 檔案轉換為深度巢狀的 JSON ，以及導致它的標頭
TOML 檔案看起來幾乎是平的，因為括號包含巢狀。 `[a.b.c]` 開啟中間表，因此其下方的 `d = 1` 變成 `{"a":{"b":{"c":{"d":1}}}}`。 JSON 大括號使 TOML 透過活動表路徑表達的層次結構可見。
ToolAcre 將語法解析委託給 smol-toml，然後標準化 JSON 無法攜帶的值。這不是基於行的重寫。表、點鍵和表格數組在 JSON 序列化之前成為普通物件和數組，這就是為什麼它們的拼字和註釋在輸出中不可用的原因。
[table] headers — 標頭如何開啟嵌套物件以及 [a.b.c] 如何隱含地建立中間對象
單括號標題開啟一個表格。 `[owner]` 將下列指派導向至 `owner`； `[owner.contact]` 建立或輸入巢狀接觸物件。中間物件不需要有單獨的標頭。它們的存在源自於標頭中的路徑段。
任何標頭之前的賦值仍保留在根中。後面的表格不會追溯移動它們。查看轉換後的 JSON 時，請遵循完整的屬性路徑，而不是行之間的物理距離：TOML 的當前表保持活動狀態，直到另一個標頭更改它。
[[表數組]] — 為什麼重複的雙括號標頭會將物件追加到陣列中，以及它保留的順序
雙括號標頭將資料表附加到陣列。兩個 `[[server]]` 部分依原始碼順序變成 `server: [{...},{...}]`。每個標頭下的欄位都屬於該陣列成員，直到另一個標頭開始，從而在 JSON 中明確重複配置。
數組內的順序是資料並被保留。當選擇該選項時，物件鍵表示稍後可能會被排序，但陣列成員永遠不會重新排序。混淆兩者會改變伺服器優先權或插件順序，而不僅僅是格式化檔案。
點鍵與內聯表 — a.b = 1 和 { x = 1 } 作為表達相同巢狀的另外兩種方式
點分配提供了另一種路徑表示法： `a.b.c = true` 產生與對應表頭相同的巢狀物件形狀。諸如 `point = { x = 1, y = 2 }` 之類的內聯表立即成為巢狀物件。這些形式可以描述相似的樹，但對於審閱者來說卻看起來非常不同。
JSON 僅記錄結果鍵和值，而不是 TOML 表示法建立它們。因此，轉換回來無法恢復標頭、點鍵和內聯表之間的原始選擇。 TOML 編寫器從樹中選擇自己的有效序列化。
繼承的類型和不繼承的類型－整數、浮點數、布林值和字串直接對應；日期時間變成字串，且 JSON null 沒有 TOML 來源
字串、安全性整數、浮點數、布林值、陣列和表格直接映射。 TOML 的四種時間類型不會：偏移日期時間、本地日期時間、本地日期和本地時間成為它們的 RFC 3339 類似來源字串，並警告會命名每個路徑和類型。作者後來引用了這些字串，而不是重新建立日期時間標記。
TOML 的符號 64 位元整數可能超出 JavaScript 的安全整數範圍。 smol-toml 在需要時傳回 BigInt 等值； ToolAcre 將它們轉換為十進位字串並發出警告，而不是四捨五入數字。這會保留拼寫，但代價是更改 JSON 類型。
工作範例：pyproject.toml — [project]、[project.Optional-dependency] 和 [[tool.plugins]] 清單轉換為 JSON 並追蹤每個層級
嘗試 `name = "demo"`、`[project]`、`dependencies = ["a", "b"]`、`[project.optional]`、`test = ["vitest"]`，然後使用兩個具有不同名稱的 `[[tool.plugins]]` 表。 JSON 將名稱放在根目錄下，嵌套項目和可選，並在工具下產生一個插件數組。
新增 `released = 1979-05-27` 和 `huge = 9223372036854775807`。第一個成為字串 `1979-05-27`；第二個變成十進位字串。這兩個警告都會識別已變更的路徑，使非 JSON 類型可審查，而不是允許靜默日期或數字強制。
這不包括什麼——使用合理的標頭分組將 JSON 轉換回慣用的 TOML，其中涉及樣式選擇，沒有規則完全確定
JSON-to-TOML，但它不會重新建立慣用的作者選擇或註解。空值鍵被省略；數組內的 null 會變成空字串以保留位置。拒絕根數組、標量或 null，因為 TOML 檔案必須是表。
此行為修正了大綱中反向轉換超出範圍的意義。轉換器寫入 TOML，但樣式保真度超出了其承諾。區別很重要：支援的序列化與逐字節恢復原始檔或選擇維護者喜歡的佈局不同。
支援將 JSON 寫回 TOML，但註解、日期時間類型和作者風格不會回傳
將 TOML 標頭讀取為路徑，將雙括號讀取為追加操作。 JSON 視圖對於追蹤結果樹很有價值，而警告會公開跨越類型邊界的日期時間和寬整數。當出現任一警告時，請勿呼叫無損操作。
對於配置遷移，請將原始檔案保留在轉換後的輸出旁邊。首先驗證值，然後編輯讀取器和目標工具的 TOML 組織。語法轉換器執行機械解析和寫入步驟；它無法決定特定於專案的分組、接受的密鑰或應用程式是否支援該檔案。
最終比較應該區分三個容易混淆的問題。首先，解析後的值是否仍然存在？其次，是否有任何 TOML-only 類型變成了 JSON 字串或任何 null 消失了？第三，新序列化的 TOML 是否以維護者可以理解的方式組織？前兩者可以根據值和警告進行檢查；第三個需要人工審查。將這些檢查分開可以防止技術上有效的序列化在其類型或授權結構發生更改時稱為忠實遷移。