Tại sao TOML tồn tại: mục tiêu thiết kế đằng sau Cargo.toml và pyproject.toml

Ba định dạng cấu hình trong một kho lưu trữ — JSON dành cho trình chỉnh sửa, YAML dành cho CI, TOML dành cho bản dựng và câu hỏi về lý do tại sao định dạng thứ ba tồn tại

Kho lưu trữ có thể sử dụng JSON, YAML và TOML cho các bề mặt cấu hình khác nhau. ToolAcre không thể giải thích lựa chọn của mọi dự án, nhưng việc chuyển đổi làm cho sự khác biệt về cấu trúc trở nên cụ thể: TOML bắt đầu dưới dạng bảng gốc, sử dụng tiêu đề và đường dẫn chấm để lồng và mang các giá trị tạm thời không có trong JSON.

Tải ví dụ thay vì tranh luận từ vẻ bề ngoài. Các bảng lồng nhau trở thành đối tượng, bảng trong ngoặc kép trở thành mảng và nhận xét biến mất khi các giá trị nhập JSON. Những ranh giới được quan sát đó có tính khả thi hơn so với tuyên bố chung chung rằng một cú pháp vốn đã tốt hơn.

Mục tiêu thiết kế - ngữ nghĩa tối thiểu, rõ ràng, dễ đọc và định dạng ánh xạ rõ ràng tới bảng băm

Trình phân tích cú pháp được vận chuyển hiển thị ngữ nghĩa bảng rõ ràng: tiêu đề là đường dẫn, phép gán thuộc về bảng đang hoạt động và mã thông báo vô hướng đã xác định loại TOML. Các chuỗi không được gõ chỉ vì nội dung của chúng trông giống như ngày tháng; cú pháp thời gian thực tế tạo ra các đối tượng ngày mà ToolAcre chuẩn hóa một cách có chủ ý.

Kho lưu trữ không ghi nguồn của người sáng tạo, ngày tháng hoặc triết lý đã nêu của định dạng, vì vậy bài viết này tránh trình bày lịch sử được ghi nhớ như một sự thật. Nó báo cáo hành vi được kiểm tra trong smol-toml và lớp chuẩn hóa của chính trình chuyển đổi.

Các thuộc tính thiết kế có thể quan sát được trong trình phân tích cú pháp được vận chuyển mà không cần xác nhận nguồn gốc không có nguồn gốc

TOML không có giá trị rỗng và gốc tài liệu của nó không thể là một mảng hoặc vô hướng. Nó không cung cấp các bí danh hoặc neo kiểu YAML trong ánh xạ này. Nhận xét tồn tại trong TOML có tác giả nhưng không được trình phân tích cú pháp giá trị giữ lại và do đó không thể tồn tại khi chuyển đổi thông qua JSON hoặc YAML.

Các giá trị trần không được trích dẫn tuân theo ngữ pháp TOML thay vì lựa chọn lược đồ của YAML. Trình phân tích cú pháp chấp nhận giá trị đã nhập hoặc báo cáo TOML không hợp lệ với thông tin vị trí. ToolAcre không thêm chế độ chuỗi ẩn cho các bài tập không đúng định dạng.

Những gì mô hình giá trị được hỗ trợ loại trừ hoặc xử lý theo cách khác

Mô hình này bao gồm các chuỗi, số nguyên có dấu, số float, boolean, bốn loại tạm thời, mảng và bảng. Mảng bảng thể hiện các bản ghi đối tượng lặp lại. Các số nguyên có dấu lớn vượt quá 2^53 trở thành chuỗi thập phân khi chuyển đổi nên JavaScript không làm tròn chúng một cách im lặng.

Các giá trị tạm thời trở thành văn bản hướng nguồn cho ngày giờ bù, ngày giờ địa phương, ngày địa phương hoặc giờ địa phương. Cảnh báo giữ nguyên loại trong văn xuôi, nhưng JSON chỉ nhận được một chuỗi. Do đó, việc chuyển đổi trở lại sẽ trích dẫn nó và mất loại TOML gốc.

Áp dụng — Hàng hóa từ những ngày đầu tiên của Rust, PEP 518 chọn pyproject.toml và thông số kỹ thuật 1.0.0 trong 2021

Việc áp dụng hàng hóa và pyproject là các xác nhận lịch sử và hệ sinh thái yêu cầu các nguồn không có trong kho chuyển đổi. Họ cố tình bỏ qua ở đây. Đường dẫn hoặc tên tệp không phải là bằng chứng cho quyết định về trình tự thời gian, thông số kỹ thuật hoặc tiêu chuẩn.

Câu hỏi vận hành là liệu công cụ đích có đọc TOML hay không và nó mong đợi bảng nào. Kiểm tra tài liệu hiện tại của công cụ đó. Bộ chuyển đổi cú pháp biết ánh xạ cú pháp và giá trị chứ không phải hợp đồng cấu hình trình quản lý gói.

Lịch sử áp dụng hệ sinh thái bị bỏ qua nếu không có nguồn kho lưu trữ

Việc lồng sâu có thể khó quét hơn vì ngữ cảnh bảng vẫn tồn tại trên các dòng, trong khi các mảng bảng lớn trải rộng một danh sách logic trên các tiêu đề lặp lại. JSON làm cho toàn bộ hệ thống phân cấp trở nên rõ ràng nhưng thêm dấu ngoặc nhọn và dấu ngoặc kép. Cả hai cách biểu diễn đều không loại bỏ được sự phức tạp khỏi cấu hình cơ bản.

Trình phân tích cú pháp lồng nhau ở 100 và độ dài nguồn là hai triệu ký tự. Đó là các ranh giới từ chối, không phải các tuyên bố về kích thước cấu hình lý tưởng hoặc các giới hạn TOML phổ quát.

Điều này không bao gồm những gì - lựa chọn trình phân tích cú pháp TOML trong mỗi ngôn ngữ và tính chất chỉ đọc của một số triển khai thư viện tiêu chuẩn

Lựa chọn trình phân tích cú pháp trong mỗi ngôn ngữ nằm ngoài phạm vi, cũng như khả năng ghi của thư viện tiêu chuẩn. ToolAcre sử dụng smol-toml một cách linh hoạt và xử lý các lỗi của nó. Cách triển khai khác có thể định dạng đầu ra hợp lệ theo cách khác hoặc hiển thị API khác trong khi biểu thị cùng một dữ liệu.

Sử dụng các công cụ cố định chéo cho các giá trị tạm thời, số nguyên lớn, mảng và các phím chấm khi khả năng tương tác có vấn đề. Tệp được chấp nhận ở đây không phải được mọi người tiêu dùng TOML tự động chấp nhận.

Bài học rút ra: TOML có ý kiến ​​​​về việc trở thành một định dạng cấu hình — và cách bảng chuyển đổi Cú pháp cho phép bạn xem bất kỳ tệp JSON hoặc YAML nào trong hình dạng đó

TOML được đưa ra ý kiến ​​theo những cách có thể quan sát được: gốc bảng, giá trị được nhập rõ ràng, loại thời gian gốc và không có giá trị rỗng. Chuyển đổi sẽ hiển thị những lựa chọn đó và sự không tương thích của chúng với các mục tiêu có hình dạng JSON mà không cần huyền thoại về nguồn gốc.

Sử dụng bảng điều khiển để kiểm tra cây và xác định các cảnh báo. Sau đó quay lại lược đồ của đích và tạo bố cục bảng mà con người sẽ duy trì. Trình chuyển đổi cung cấp bằng chứng về các giá trị chứ không phải là phán quyết về ưu tiên định dạng.

Nguyên tắc tương tự được áp dụng khi TOML chỉ là chế độ xem trung gian. Bảo toàn nguồn, so sánh các giá trị chuẩn hóa và lưu ý mọi chuyển đổi theo thời gian hoặc số nguyên rộng trước khi đánh giá khả năng đọc. Bố cục bảng nhỏ gọn vẫn có thể ẩn loại đã thay đổi, trong khi một mảng bảng dài dòng có thể chính xác về mặt ngữ nghĩa. Lựa chọn định dạng phải tuân theo hợp đồng cấu hình và quy trình bảo trì, chứ không phải sự gọn gàng trực quan của một mẫu được tạo.