Công cụ dành cho nhà phát triển · Trình chuyển đổi cú pháp
Cách các bảng TOML trở thành đối tượng JSON: [bảng], [[mảng]] và các phím chấm
· Cách thức hoạt động
toml json data-formats
Tiêu đề của TOML trông không giống dấu ngoặc nhọn của JSON nhưng chúng xác định chính xác cách lồng nhau. Bài đăng này giải thích cách [máy chủ], [[sản phẩm]] và a.b.c ánh xạ lên các đối tượng và mảng JSON cũng như nơi hai mô hình phân kỳ.
Việc làm tổ đến từ đâu? — một tệp TOML có giao diện phẳng được chuyển đổi thành JSON được lồng sâu và các tiêu đề gây ra lỗi đó
Tệp TOML có thể xuất hiện gần như phẳng vì dấu ngoặc mang tính chất lồng nhau. `[a.b.c]` mở các bảng trung gian, vì vậy `d = 1` bên dưới nó trở thành `{"a":{"b":{"c":{"d":1}}}}`. Các dấu ngoặc nhọn JSON hiển thị cấu trúc phân cấp mà TOML thể hiện thông qua đường dẫn bảng đang hoạt động.
ToolAcre ủy quyền phân tích cú pháp thành smol-toml và sau đó chuẩn hóa các giá trị JSON không thể mang theo. Đây không phải là viết lại theo dòng. Các bảng, các phím chấm và mảng bảng trở thành các đối tượng và mảng thông thường trước khi JSON tuần tự hóa, đó là lý do tại sao chính tả và nhận xét của chúng không có trong kết quả đầu ra.
Tiêu đề [bảng] - cách tiêu đề mở một đối tượng lồng nhau và cách [a.b.c] tạo các đối tượng trung gian một cách ngầm định
Tiêu đề một khung đơn sẽ mở ra một bảng. `[owner]` chuyển các nhiệm vụ sau vào `owner`; `[owner.contact]` tạo hoặc nhập đối tượng liên hệ lồng nhau. Các đối tượng trung gian không cần phải có tiêu đề riêng biệt. Sự tồn tại của chúng xuất phát từ các đoạn đường dẫn trong tiêu đề.
Bài tập trước bất kỳ tiêu đề nào vẫn ở gốc. Các bảng sau này không di chuyển chúng trở về trước. Khi xem xét JSON đã chuyển đổi, hãy đi theo đường dẫn thuộc tính đầy đủ thay vì khoảng cách vật lý giữa các dòng: bảng hiện tại của TOML vẫn hoạt động cho đến khi một tiêu đề khác thay đổi nó.
[[mảng bảng]] — tại sao tiêu đề trong ngoặc kép lặp lại sẽ gắn các đối tượng vào một mảng và giữ nguyên thứ tự
Tiêu đề trong ngoặc kép sẽ nối một bảng vào một mảng. Hai phần `[[server]]` trở thành `server: [{...},{...}]` theo thứ tự nguồn. Các trường bên dưới mỗi tiêu đề thuộc về thành viên mảng đó cho đến khi một tiêu đề khác bắt đầu, làm cho cấu hình lặp lại trở nên rõ ràng trong JSON.
Thứ tự bên trong mảng là dữ liệu và được giữ nguyên. Bản trình bày khóa đối tượng sau này có thể được sắp xếp khi tùy chọn được chọn, nhưng các thành viên mảng không bao giờ được sắp xếp lại. Việc nhầm lẫn cả hai sẽ thay đổi mức độ ưu tiên của máy chủ hoặc trình tự plugin thay vì chỉ định dạng tài liệu.
Phím chấm và bảng nội tuyến — a.b = 1 và { x = 1 } là hai cách khác để thể hiện cùng một cách lồng nhau
Các phép gán chấm cung cấp một ký hiệu đường dẫn khác: `a.b.c = true` mang lại hình dạng đối tượng lồng nhau giống như các tiêu đề bảng tương ứng. Các bảng nội tuyến như `point = { x = 1, y = 2 }` trở thành đối tượng lồng nhau ngay lập tức. Những biểu mẫu này có thể mô tả những cây tương tự nhưng trông rất khác đối với người đánh giá.
JSON chỉ ghi lại các khóa và giá trị kết quả chứ không phải ký hiệu TOML đã tạo ra chúng. Do đó, việc chuyển đổi trở lại không thể khôi phục lựa chọn ban đầu giữa các tiêu đề, phím chấm và bảng nội tuyến. Trình ghi TOML chọn chuỗi tuần tự hợp lệ của riêng nó từ cây.
Các loại mang theo và các loại không - số nguyên, số float, boolean và chuỗi ánh xạ trực tiếp; ngày giờ trở thành chuỗi và JSON null không có nguồn TOML
Chuỗi, số nguyên an toàn, số float, boolean, mảng và bảng ánh xạ trực tiếp. Bốn loại thời gian của TOML không: bù ngày giờ, ngày giờ địa phương, ngày địa phương và giờ địa phương trở thành các chuỗi nguồn giống RFC 3339 của chúng và cảnh báo đặt tên cho từng đường dẫn và loại. Người viết sau đó trích dẫn những chuỗi đó thay vì tạo lại mã thông báo ngày giờ.
Số nguyên bit 64 đã ký của TOML có thể vượt quá phạm vi số nguyên an toàn của JavaScript. smol-toml trả về các giá trị như BigInt khi cần; ToolAcre chuyển đổi chúng thành chuỗi thập phân và cảnh báo thay vì làm tròn chữ số. Điều này duy trì chính tả nhưng phải thay đổi loại JSON.
Ví dụ đã hoạt động: một danh sách pyproject.toml — [dự án], [project.optional-phụ thuộc] và một danh sách [[tool.plugins]] được chuyển đổi thành JSON với mỗi cấp độ được theo dõi
Hãy thử `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, sau đó hai bảng `[[tool.plugins]]` có tên riêng biệt. JSON đặt tên ở gốc, lồng dự án và tùy chọn, đồng thời tạo ra một mảng plugin bên dưới công cụ.
Thêm `released = 1979-05-27` và `huge = 9223372036854775807`. Chuỗi đầu tiên trở thành chuỗi `1979-05-27`; thứ hai trở thành một chuỗi thập phân. Both warnings identify the changed paths, making the non-JSON types reviewable instead of allowing silent Date or Number coercion.
Điều này không bao gồm những gì - chuyển đổi JSON trở lại thành ngữ TOML với nhóm tiêu đề hợp lý, bao gồm các lựa chọn kiểu mà không có quy tắc nào xác định đầy đủ
JSON-to-TOML is supported for a root object, but it does not recreate idiomatic author choices or comments. Các khóa có giá trị null bị bỏ qua; null inside an array becomes an empty string to preserve positions. A root array, scalar or null is refused because a TOML document must be a table.
That behaviour corrects the outline’s implication that reverse conversion is outside scope. The converter writes TOML, yet style fidelity is outside its promise. Vấn đề khác biệt là: việc tuần tự hóa được hỗ trợ không giống như việc khôi phục byte tệp nguồn cho byte hoặc chọn bố cục mà người bảo trì muốn.
Viết JSON quay lại TOML được hỗ trợ, nhưng các nhận xét, loại ngày giờ và kiểu tác giả không trả về
Read TOML headers as paths and double brackets as append operations. Chế độ xem JSON có giá trị để theo dõi cây kết quả, trong khi các cảnh báo hiển thị ngày giờ và số nguyên rộng vượt qua ranh giới loại. Do not call the operation lossless when either warning appears.
Để di chuyển cấu hình, hãy giữ bản gốc bên cạnh đầu ra đã chuyển đổi. Trước tiên hãy xác minh giá trị, sau đó chỉnh sửa TOML tổ chức cho người đọc và công cụ mục tiêu. Bộ chuyển đổi cú pháp thực hiện bước phân tích cú pháp và ghi cơ học; nó không thể quyết định việc phân nhóm theo dự án cụ thể, các khóa được chấp nhận hoặc liệu ứng dụng có hỗ trợ tệp đó hay không.
A final comparison should separate three questions that are easy to blur together. Đầu tiên, các giá trị được phân tích có tồn tại không? Second, did any TOML-only type become a JSON string or any null disappear? Third, is the newly serialized TOML organized in a way a maintainer can understand? The first two can be checked against values and warnings; thứ ba cần sự xem xét của con người. Việc giữ riêng các bước kiểm tra đó sẽ ngăn không cho việc xê-ri hóa hợp lệ về mặt kỹ thuật được gọi là di chuyển trung thực khi loại hoặc cấu trúc tác giả của nó thay đổi.