Di chuyển cấu hình JSON sang TOML: nội dung chuyển đổi và nội dung cần có con người

Kỷ nguyên setup.cfg và settings.json sắp kết thúc — một dự án hợp nhất cấu hình thành pyproject.toml và các khối JSON cần di chuyển

Các dự án đôi khi hợp nhất các cài đặt thành một tệp TOML nhưng kho lưu trữ không thể hỗ trợ tuyên bố của phác thảo rằng một “kỷ nguyên đang kết thúc”. Nhiệm vụ thực tế hẹp hơn: di chuyển một đối tượng có hình dạng JSON vào bảng TOML, kiểm tra các tổn thất, sau đó xác minh rằng ứng dụng đích có thực sự nhận ra các khóa kết quả hay không.

ToolAcre yêu cầu đối tượng gốc cho đầu ra TOML. Mảng gốc, chuỗi, số, Boolean hoặc null bị từ chối vì tài liệu TOML là một bảng. Việc kiểm tra hình dạng ban đầu đó sẽ ngăn không cho trình bao bọc được phát minh trông giống cấu hình được ứng dụng phê duyệt.

Hợp nhất cấu hình là một lựa chọn của dự án, không phải là mục đích phổ biến của các định dạng cũ hơn

Trình chuyển đổi chứng minh cơ học cụ thể: TOML có bảng, mảng và giá trị vô hướng; người viết nó biến các đối tượng lồng nhau thành các cấu trúc TOML hợp lệ. Nó cũng không có giá trị rỗng và sử dụng cú pháp khác với dấu ngoặc nhọn JSON. Các tuyên bố về ưu tiên hệ sinh thái hoặc tính ưu việt của thiết kế yêu cầu các nguồn bên ngoài các tệp triển khai này.

Nhận xét là một lý do khiến người bảo trì có thể thích TOML có tác giả hơn, tuy nhiên thông tin đầu vào JSON không chứa nội dung nào để chuyển qua. Tài liệu được tạo là sự tuần tự hóa giá trị bắt đầu. Giải thích về con người và tổ chức dự án cụ thể phải được bổ sung sau đó.

Công cụ chuyển đổi này chứng minh điều gì về TOML thay vì ủng hộ định dạng chung

Chuỗi, số hữu hạn, boolean, đối tượng lồng nhau và mảng được hỗ trợ bởi smol-toml chuyển đổi một cách máy móc. Mảng đối tượng có thể trở thành mảng bảng; các đối tượng lồng nhau có thể trở thành tiêu đề bảng. Unicode và các dòng mới thoát vẫn tồn tại trong các chuyến đi khứ hồi đã được thử nghiệm đối với các giá trị thông thường.

TOML quy tắc mảng có thể từ chối các hình dạng mà người viết của nó không thể diễn đạt và đặt tên lỗi mà lỗi thay vì ép buộc một cách âm thầm. Việc gọi trước tất cả các mảng là đồng nhất sẽ đơn giản hóa quá mức hành vi được kiểm tra của phần phụ thuộc, thậm chí còn đọc các mảng không đồng nhất. Sử dụng chuyển đổi thực tế làm cổng.

Những gì chuyển đổi một cách máy móc, bao gồm các mảng mà người viết TOML chấp nhận

Null không có đại diện TOML. Thuộc tính đối tượng chứa null sẽ bị bỏ qua và liệt kê trong cảnh báo. Giá trị rỗng bên trong một mảng sẽ trở thành một chuỗi trống để các chỉ mục sau này không thay đổi; sự thay thế đó cũng được đặt tên. Không có kết quả nào giữ nguyên giá trị ban đầu.

Quyết định ý nghĩa của null trước khi chấp nhận thay đổi. Nó có thể có nghĩa là kế thừa một giá trị mặc định, xóa một trường một cách rõ ràng hoặc không có giá trị nào được cung cấp. Việc xóa khóa hoặc thay thế văn bản trống có thể thay đổi ngữ nghĩa của ứng dụng, do đó hãy giải quyết nó dựa trên mô hình cấu hình được ghi lại của đích.

Khi phong cách cần con người — chọn giữa tiêu đề [bảng], phím chấm và bảng nội tuyến, đồng thời nhóm các khóa liên quan để tệp đọc tốt

Cây không cho biết người bảo trì thích `[tool.linter]`, phím chấm hay bảng nội tuyến. Trình tuần tự hóa chọn cú pháp hợp lệ, trong khi con người chọn nhóm giúp làm rõ quyền sở hữu và các tùy chọn liên quan. Các khóa sắp xếp có thể làm cho kết quả đầu ra mang tính xác định nhưng có thể tách biệt các khái niệm thuộc về nhau.

Giữ lại một khác biệt nhỏ và thêm nhận xét sau khi giá trị được xác minh. Việc chuyển đổi TOML trở lại JSON sau này không thể khôi phục các nhận xét đó hoặc cách viết chính tả của bảng đã chọn. Phong cách là thông tin được tác giả bên ngoài mô hình giá trị đơn giản.

Ví dụ đã hoạt động: cấu hình JSON của kẻ nói dối thành TOML — chuyển đổi, phân giải hai giá trị null và nhóm lại kết quả dưới tiêu đề [tool.linter]

Chuyển đổi `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. Đối tượng gốc được chấp nhận. `preview` bị bỏ qua; thành viên mảng null trở thành một chuỗi rỗng; cảnh báo đặt tên cho cả hai đường dẫn. Đối tượng lồng nhau còn lại được tuần tự hóa trong các bảng TOML do người viết chọn.

Trước khi lưu, hãy quyết định xem bản xem trước có phải là giá trị sai, không có hoặc giá trị được ghi lại khác và liệu mục nhập loại trừ trống có hợp lệ hay không. Sau đó tập hợp lại và nhận xét bảng cho bạn đọc. Ví dụ này chứng minh tại sao chuyển đổi là cơ học trong khi di chuyển là ngữ nghĩa.

Điều này không đề cập đến — liệu công cụ đích có thực sự đọc TOML hay không và các tên khóa cụ thể của nó mà chỉ tài liệu của nó mới có thể cho bạn biết

Tệp TOML hợp lệ không chứng minh rằng công cụ đọc TOML, nhận dạng phần hoặc diễn giải các khóa giống như ứng dụng tiêu dùng JSON cũ. Kiểm tra tài liệu mục tiêu hiện tại và chạy lệnh xác thực hoặc chạy thử của chính nó. ToolAcre không bao giờ nhập lược đồ ứng dụng.

Chà là cũng xứng đáng được chăm sóc theo hướng ngược lại. TOML-giá trị thời gian gốc trở thành chuỗi khi được đọc vào JSON, do đó, chuyến đi khứ hồi sau đó sẽ trích dẫn chúng. Một chuỗi di chuyển qua cả hai hướng không thể được gọi là lossless.

Bài học rút ra: chuyển đổi trước, sau đó chỉnh sửa để dễ đọc — và cách bảng chuyển đổi Cú pháp thực hiện phần cơ học trong trình duyệt của bạn

Đầu tiên hãy chuyển đổi để bộc lộ những điểm không tương thích về mặt cơ học, sau đó chỉnh sửa ngữ nghĩa và khả năng đọc. Giữ bản gốc, xem lại mọi cảnh báo và kiểm tra với mục tiêu thực tế. Xử lý null và hình dạng gốc là ranh giới cứng; tổ chức bảng là một quyết định thiết kế của con người.

Trình chuyển đổi cú pháp loại bỏ công việc cú pháp lặp đi lặp lại mà không phát minh ra kiến ​​thức ứng dụng. Sự phân chia đó làm cho kết quả đầu ra trở nên hữu ích: cấu trúc do máy tạo ra để xem xét, theo sau là những lựa chọn có chủ ý trong đó các định dạng hoặc công cụ không đồng nhất.

Giữ một ghi chú di chuyển cho mỗi cảnh báo bạn chấp nhận. Nếu giá trị rỗng trở thành vắng mặt, hãy nêu mặc định đích khiến cho sự vắng mặt là chính xác. Nếu một thành viên mảng null trở thành văn bản trống, hãy giải thích lý do tại sao chỉ mục lại quan trọng và tại sao văn bản trống lại hợp lệ. Nếu người viết từ chối một mảng hỗn hợp, hãy thiết kế lại giá trị đó thay vì ép buộc nó một cách riêng tư. Những quyết định này là hồ sơ di cư lâu dài; riêng TOML được tạo không thể giải thích chúng cho người bảo trì tiếp theo.