將 JSON 配置遷移到 TOML：什麼會轉換以及什麼需要人工

setup.cfg 和 settings.json 時代即將結束 - 一個將配置合併到 pyproject.toml 和需要移動的 JSON 區塊的項目

專案有時會將設定合併到一個 TOML 檔案中，但儲存庫無法支援大綱中「時代正在結束」的說法。實際任務範圍較小：將 JSON 形狀的物件移至 TOML 表中，檢查損失，然後驗證目標應用程式是否確實識別產生的金鑰。

ToolAcre 需要 TOML 輸出的根物件。拒絕根數組、字串、數字、布林值或 null，因為 TOML 檔案是一個表。早期的形狀檢查可以防止發明的包裝器看起來像是應用程式批准的配置。

配置整合是專案選擇，而不是舊格式的通用結束

轉換器證明了具體的機制： TOML 有表、陣列和標量值；它的編寫器將巢狀物件轉換為有效的 TOML 結構。它也沒有 null 並使用與 JSON 大括號不同的語法。關於生態系統偏好或設計優越性的主張需要這些實施檔案以外的來源。

註解是維護者可能更喜歡寫 TOML 的原因之一，但 JSON 輸入不包含任何內容。產生的文件是起始值序列化。之後必須添加人工解釋和特定於項目的組織。

此轉換器證明了 TOML 而不是一般格式倡導

smol-toml 支援的字串、有限數字、布林值、巢狀物件和陣列進行機械轉換。物件數組可以變成表格數組；嵌套物件可以成為表頭。 Unicode 和轉義換行符號可以通過普通值的往返測試。

TOML 陣列規則可以拒絕其編寫者無法表達的形狀，並錯誤名稱會失敗，而不是默默地強制。提前將所有陣列稱為同質數組會過度簡化依賴項的測試行為，甚至會讀取異質數組。以實際轉換為門。

機械轉換的內容，包括 TOML writer 接受的陣列

Null 沒有 TOML 表示。保留 null 的物件屬性將被省略並在警告中列出。數組內的 null 會變成空字串，因此後面的索引不會移動；該替代品也被命名。這兩種結果都不會保留原始值。

在接受任何變更之前確定 null 的意思。這可能意味著繼承預設值、明確清除欄位或不提供任何值。刪除密鑰或替換空白文字可能會改變應用程式語義，因此請根據目標記錄的配置模型來解析它。

樣式需要人為的地方 - 在[表]標題、點鍵和內聯表之間進行選擇，並對相關鍵進行分組，以便檔案閱讀良好

此樹沒有說明維護者是否偏好 `[tool.linter]`、點鍵或內聯表。序列化程序選擇有效的語法，而人類選擇使所有權和相關選項清晰的分組。排序鍵可以使輸出具有確定性，但可能分離屬於在一起的概念。

保留小差異並在驗證值後新增註解。稍後將 TOML 轉換回 JSON 無法復原這些註解或所選的表格拼字。風格是在簡單價值模型之外創作的訊息。

工作範例：linter 的 JSON 配置為 TOML — 轉換、解析兩個空值並將結果重新分組到 [tool.linter] 標頭下

轉換 `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`。根對像被接受。 `preview` 被省略； null 陣列成員變成空字串；警告命名了這兩條路徑。剩餘的巢狀物件在作者選擇的 TOML 表下序列化。

在儲存之前，確定預覽是否應為 false、不存在或其他記錄值，以及空的排除條目是否有效。然後重新整理表格並為讀者進行評論。這個範例說明了為什麼轉換是機械的，而遷移是語義的。

這不包括什麼 - 目標工具是否實際讀取 TOML 及其特定鍵名稱，只有其檔案可以告訴您

有效的 TOML 檔案無法證明工具可以讀取 TOML、識別該部分或像舊的 JSON 使用者一樣解釋鍵。檢查目前目標檔案並執行其自己的驗證或試執行命令。 ToolAcre 從不匯入應用程式架構。

日期也值得反向關注。 TOML-本機時間值在讀入 JSON 時會變成字串，因此稍後的往返會引用它們。跨越兩個方向的遷移鏈不能稱為無損。

重點：先轉換，然後編輯以提高可讀性 - 以及語法轉換器面板如何在瀏覽器中執行機械部分

首先進行轉換以暴露機械不相容性，然後進行語義和可讀性編輯。保留原始內容，查看每個警告並根據實際目標進行測試。空處理和根形狀是硬邊界；表格組織是人為設計的決定。

語法轉換器消除了重複的語法工作，而無需發明應用程式知識。這種劃分使得輸出變得有用：機器產生的結構供審查，然後在格式或工具不一致的地方進行深思熟慮的選擇。

為您接受的每個警告保留遷移註解。如果空值變成缺席，請說明使缺席正確的目標預設值。如果空數組成員變成空文字，請解釋為什麼索引很重要以及為什麼空文字有效。如果編寫者拒絕混合數組，請重新設計該值，而不是私下強制它。這些決定是持久的遷移記錄；僅產生的 TOML 無法向下一個維護者解釋它們。