TOML 第一次咬我,不是語法。這是排序。我有一個來自舊節點服務的 JSON 設定對象,我想要它作為一個 config.toml 為了重寫 Rust,我做了每個人第一次都會做的事情:我手工輸入表格。十分鐘後,解析器出現了一個我不明白的錯誤,指向一條看起來非常好的線。問題是三個鍵位於 a 下方 [table] 屬於它上方的標頭。 TOML 有一條 JSON 沒有的規則,一旦你絆倒它,你就永遠不會忘記它。
我建造 工具。dev,我已經在那裡運送了一長架格式轉換器,所以我編寫了 JSON 到 TOML 轉換器以消除整個類別的錯誤。你貼上 JSON,你得到重新解析相同資料的 TOML,然後為您處理排序。我希望那天下午我讀到這本指南:TOML 是什麼,JSON 和 TOML 不同意,以及如何在不丟失任何你關心的東西的情況下在它們之間進行轉換。
TL;DR: TOML 是 Cargo、Poetry、Hugo 和許多 Rust and Go 工具使用的類型化配置格式。將 JSON 轉換為 TOML 主要是機械的,但需要判斷三件事:表排序(鍵在子表之前,始終)、如何編寫物件數組(表數組與內聯表)以及 JSON 會發生什麼
null,TOML 無法表達。這 JSON 到 TOML 轉換器 使所有三個都明確並完全在瀏覽器中運行。
什麼是 TOML,為什麼要將 JSON 轉換為它?
TOML 代表 Tom's 明顯的、最小的語言。它讀起來就像一個舊的 INI 文件,但與 INI 不同的是,它有一個真實的規範,其中包含鍵入的值、一流的日期和定義的語法。該規範是它獲勝的原因:一個人可以一目了然地閱讀的配置格式,機器每次都以相同的方式解析,對於是否如此沒有歧義 port = 8080 是一個字串或一個數字。它是一個數字,因為 TOML 是這麼說的。
當機器為您提供 JSON 且工具想要 TOML 時,您就可以進行 JSON 到 TOML 的轉換。這種情況發生的比您想像的要多。 API 將設定 blob 傳回為 JSON,您需要它 pyproject.toml.你有一個老 config.json 您正在將項目移動到一個堆疊中,該堆疊會讀取 config.toml。 您以程式設計方式產生了一些數據,結果為 JSON,因為就是這樣 JSON.stringify 使用 TOML 庫生產、消費者是 Cargo 或 Hugo 或 Go 服務。在每種情況下,資料都是相同的。只是序列化不同。
反向也存在,但這是一項不同的工作。如果你走另一條路,那 JSON 格式化程式 值得保持理智,先檢查 JSON,然後 JSON 到 YAML 轉換器 涵蓋其他常見的配置格式。本指南是關於 JSON 進入 TOML 的。
轉換器如何將 JSON 對應到 TOML?
JSON 中只有少數形狀,每個形狀在 TOML 中都有一個家。了解映射是了解工具的大部分。
一個JSON 對象 成為 TOML 表。 頂層物件是根表,這就是為什麼轉換器堅持輸入是物件的原因。嵌套物件變成 [table] 具有虛線路徑的標頭,因此 { "database": { "pool": { "max": 10 } } } 成為a [database.pool] 部分與 max = 10 在裡面。
一個JSON 物件數組 成為 TOML 表格數組,用雙括號寫成 [[name]] 標頭,每個元素一個區塊。這是記錄清單的慣用 TOML 模式:伺服器清單、依賴項清單、建置目標清單。每個元素都有自己的 [[servers]] 塊。
每一個 標量 直接映射。 JSON 字串成為雙引號中的 TOML 基本字串,控製字元轉義。如果 JSON 數字是整數,否則 JSON 數字將成為 TOML 整數。 JSON 布林值變為 true 或者 false. 這些都是簡單的情況,轉換器永遠不會弄錯它們。
一個JSON 標量數組 成為 TOML 內聯數組: ["admin", "editor"] 留下來 ["admin", "editor"]. 混合數組和嵌套數組也是內聯編寫的,因為這是它們唯一適合的地方。
為什麼鍵排序在 TOML 中如此重要?
這是吸引所有人的規則,因此值得簡單說明。在 TOML 中,在任何表中,所有該表和#39;自己的鍵/值對必須出現在其任何子表標頭之前。如果你寫了一個 [server] 標頭,然後是一些鍵,然後是屬於根表的另一個鍵,解析器將雜散鍵讀取為 的一部分 [server] 相反。最好的情況是它落在錯誤的地方;最壞的情況是文件無法解析。
JSON 沒有這樣的規則。在 JSON 中,鍵順序甚至不重要,物件和標量在同一大括號內自由混合。因此,簡單的 JSON 到 TOML 轉換會按照插入順序遍歷物件並在每個鍵發出時,一旦標量跟隨嵌套對象,就會產生損壞的 TOML。
轉換器透過每張表兩次傳遞來解決這個問題。首先,它發出所有簡單的鍵、標量和內聯數組。只有這樣,它才會發出子表和表數組標頭,遞歸到每個標頭。您的密鑰順序保留在每個群組內,這是您想要的,但兩個群組之間所需的重新排列會自動發生。你永遠不必考慮它,也永遠不會得到我得到的錯誤。
物件數組什麼時候應該是表而不是內聯?
這是一個真正的選擇。一系列物件可以用 TOML 兩種方式編寫,並且都是有效的。
第一個是 表格數組,雙括號形式。它冗長且可讀,每筆記錄一個區塊,這就是大多數野外 TOML 的樣子。如果你見過 Cargo.toml 與幾個 [[bin]] 條目,你已經看到了。
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
第二個是a 內聯表 在普通陣列內,將每個物件打包到一行上。
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
兩次往返相同的數據。您想要哪一個取決於目標和品味。表格數組讀起來更好,可以記錄人類將編輯的記錄,它們是大多數工具配置的約定。內聯表更緊湊,更接近原始 JSON 的形狀,當清單很短或物件很小時,有些人更喜歡它。轉換器預設為表格數組,並為您提供切換切換的切換。如果您不確定,請將其保留在預設值上:這就是 TOML 檔案通常的樣子。
TOML 中的 JSON null 會發生什麼情況?
TOML 沒有空。沒有關鍵字,沒有空值,什麼都沒有。這是格式故意的設計決策,也是 JSON 到 TOML 真正有損的地方。
所以轉換器必須做出選擇,它讓你做出選擇。預設情況下,鍵的值為 null 被刪除,工具在輸出下方的註釋中列出了刪除的鍵,因此沒有任何內容會靜默消失。如果您願意保留該鍵,您可以切換為將 null 寫為空字串,這會以更改其類型為代價來保留該鍵。兩者都不是完美的,因為沒有完美的答案。重要的是選擇是可見的而不是被埋葬的。
數組內的 Null 始終會刪除,並帶有警告,因為 TOML 數組根本無法包含 null。如果您的 JSON 有 [1, null, 3],TOML 將是 [1, 3] 該工具會告訴您它已刪除一個。如果這些空值具有意義,則表示在轉換之前而不是之後重塑資料。
為什麼我的數字失去了小數,或增加了一個?
這讓關心類型的人感到驚訝。 JSON 不區分 5 從 5.0。 兩者都解析為同一個 IEEE 754 雙倍,並且到時間 JSON.parse 完成後就沒有尾隨零的痕跡了。所以當轉換器看到數字時 5,它無法知道你的意思是漂浮,從那時起 5 是整數,它寫一個TOML整數。
另一方面,TOML 確實區分了整數和浮點數,有些工具關心差異。如果您需要一個鍵入為浮點的值,修復方法是給它來源中的一個小數部分 5.1 或者 5.0 以保留的方式編寫,或在轉換後編輯單一值。這是一個字元更改,這種情況很少見,但值得知道為什麼會發生這種情況,而不是假設轉換器是錯誤的。這並沒有錯。 JSON 只是在轉換器看到訊息之前就將訊息丟棄了。
相反的情況顯示為非常大或非常小的數字,其中 JavaScript's String() 產生指數符號,如 1e+21. TOML 接受它作為浮點數,因此轉換得很好,但數字的形狀可能看起來與您輸入的形狀不同。同樣,該值是相同的;只是渲染發生了變化。
裸鍵和引用鍵如何運作?
如果一個金鑰僅由字母、數字、底線和破折號組成,TOML 允許將其寫成裸露。任何其他內容,都必須引用帶有點、空格、斜線、Unicode 字元的金鑰。轉換器檢查每個鍵並僅引用需要的鍵,因此 user-name 保持裸露和 "user.name" 取得引號以阻止將點讀取為表格路徑。您不必考慮這一點,但如果您在輸出中看到某個鍵周圍的引號,這就是原因:該鍵包含一個字符,否則該字符將改變其含義。
一個可行的例子
這是工具載入的範例,因此您可以同時查看每個規則。 JSON:
{
"title": "Toolz config",
"version": 2,
"enabled": true,
"owner": { "name": "Liton", "roles": ["admin", "editor"] },
"database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
"servers": [
{ "name": "web", "ip": "10.0.0.1" },
{ "name": "api", "ip": "10.0.0.2" }
]
}
變成 TOML,其中根標量排在第一位,嵌套物件依序變成點表,伺服器陣列變成兩個 [[servers]] 塊:
title = "Toolz config"
version = 2
enabled = true
[owner]
name = "Liton"
roles = ["admin", "editor"]
[database]
host = "localhost"
port = 5432
[database.pool]
min = 2
max = 10
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
注意這一點 title, version 和 enabled 寫在任何標題之前, roles 保持內聯數組,因為它是字串數組,並且 [database.pool] 坐在下面 [database] 作為虛線路徑。本指南中的每條規則在九行輸出中可見。
哪種工具需要轉換?
TOML 是家庭中的格式,正確的工具取決於您的開始和結束位置。這就是我的想法。
| 你有 | 你想要 | 使用 |
|---|---|---|
| 傑森 | TOML 配置 | JSON 到 TOML |
| 傑森 | YAML 配置 | JSON 到 YAML |
| 亞姆爾 | 傑森 | YAML 至 JSON |
| 傑森 | XML | json 到 xml |
| 凌亂的 JSON | 可讀的 JSON | JSON 格式化程式 |
模式是配置格式是相同資料的可互換視圖,並且您想要的轉換器以您要去的方向命名。 TOML、YAML 和 JSON 都表達嵌套鍵/值資料;區別在於您的目標工具讀取的是哪一個。
在線上轉換設定檔安全嗎?
設定檔正是您貼上到網站時應小心的事情,因為它們通常包含連接字串、令牌和其他秘密。這 JSON 到 TOML 轉換器 完全在瀏覽器中運作。您貼上後的 JSON 會在裝置上的記憶體中解析,TOML 在那裡生成,並且不會向伺服器發送任何內容、寫入日誌或儲存。您可以自己查看:開啟網路選項卡,執行轉換,並查看沒有請求發出。一旦頁面加載,它也會保持不連接的工作,這是工作是本地的實際證明。如果您關心資料的去向,並且使用設定文件,那麼這就是重要的屬性。網站上的每個工具背後的原理相同,也是我在註釋中詳細描述它的原因 線上工具中的資料隱私.
這適合實際工作流程
格式轉換很少是整個任務。這是一個步驟。你從 API 中提取一個設定對象,將其轉換,然後將其放入專案中。客戶端轉換器的價值在於它可以毫無摩擦地插入該流程:沒有上傳,沒有帳戶,沒有在伺服器上等待,不知道您的秘密現在是否在某人中'日誌。這就是我保留整體的原因 工具。dev 設定客戶端,這是我在《 開發人員生產力工具 寫下來,因為您每天使用二十次的工具是兩秒往返和隱私問題加起來的工具。
TOML 透過以最好的方式鑽孔而贏得了在該流程中的地位。它到處解析相同,讀數良好,並且它的一個尖銳邊緣,即排序規則,正是轉換器應該為您歸檔的東西。貼上您的 JSON,選擇處理陣列和空值的方式,然後複製正常工作的 TOML。
常見問題
如何將 JSON 轉換為 TOML?
將 JSON 物件貼上到轉換器中,然後按一下「轉換」。該工具將物件序列化為 TOML 表,將物件數組序列化為表數組,並將所有其他值內聯,然後為您提供標準 TOML 進行複製。頂級 JSON 必須是一個對象,因為 TOML 文件始終是一個表。
TOML 有何用途?
TOML 是一種設定檔格式,旨在易於閱讀且易於解析。它是 Rust's Cargo (Cargo。toml)、Python packaging (pyproject。toml)、Hugo 以及許多 Go 和 Rust 工具的設定格式。人們將 JSON 轉換為 TOML,將機器產生的配置交給期望 TOML 的工具。
TOML 中的 JSON 空值會發生什麼變化?
TOML 沒有 null 類型,因此無法直接表示 JSON null。預設情況下,此轉換器會丟棄 null 鍵並新增列出它們的註解;您可以切換到將它們寫為空字串。數組內的 Null 始終會刪除,因為 TOML 數組不能包含 null。
表數組和內聯表有什麼不同?
表數組使用重複的雙括號標頭,每筆記錄一個區塊,是編寫物件清單(例如伺服器或依賴項清單)的慣用 TOML 方式。內聯表將物件打包到一行上,作為一組鍵等於大括號中的值對。此工具預設為表格數組,但允許您選擇內聯。
為什麼我的 JSON 5.0 在 TOML 中變成了 5?
JSON 不保留 5 和 5.0 之間的差異,因此解析將兩者讀取為數字 5。由於 5 是整數,因此轉換器將其寫入 TOML 整數。如果您需要將其鍵入為浮點數,請在來源中新增小數部分或在轉換後編輯單一值。
轉換器會保留我的鑰匙訂單嗎?
是的。按鍵按照 JSON 中出現的順序發出,需要進行重新排列:在每個表中,普通鍵都寫在任何子表或表數組標頭之前。這是 TOML 語法規則,而不是重新排序選擇,如果沒有它,檔案將無法解析。
我的 JSON 上傳到伺服器了嗎？
不。整個轉換是在您的瀏覽器中使用普通 JavaScript 進行的。您的 JSON(包括設定檔中的任何秘密或憑證)永遠不會傳輸、記錄或存儲,並且一旦頁面加載,轉換器就會在沒有連接的情況下繼續工作。
為什麼說頂層一定是物體?
TOML 文件被定義為一個表,這意味著它必須從一組鍵/值對開始。裸 JSON 數組或標量沒有表可以對應到。首先將其包裝在物件中,例如將數組放在指定的鍵下,然後它就會轉換。
