Chuyển đổi TOML: mô hình bảng, kiểu ngày giờ và những gì rơi rớt qua mỗi lần đổi định dạng
Công cụ đọc TOML bằng bộ phân tích tự viết rồi ghi lại thành JSON hoặc YAML, và làm được cả chiều ngược lại. Bộ đọc hiểu bảng lồng, mảng bảng viết bằng hai cặp ngoặc vuông, bảng nội tuyến, bốn kiểu ngày giờ, chuỗi ba nháy nhiều dòng và số có dấu gạch dưới ngăn nhóm.
Tính năng nổi bật
- Chuyển hai chiều giữa ba định dạng TOML, JSON và YAML bằng hai ô chọn nguồn và đích
- Bộ đọc TOML tự viết: bảng thường, bảng lồng nhiều tầng, mảng bảng, bảng nội tuyến, khóa chấm
- Nhận đủ bốn kiểu thời gian của TOML và ghi lại chúng không bọc nháy khi quay về TOML
- Hiểu số hệ mười sáu, hệ tám, hệ hai, số có dấu gạch dưới ngăn nhóm, vô cực và không phải số
- Chuỗi cơ bản, chuỗi nguyên văn, chuỗi ba nháy nhiều dòng kèm nối dòng bằng dấu gạch chéo ngược
- Báo lỗi kèm số dòng, chỉ rõ thiếu dấu bằng, thiếu dấu đóng hay khóa bị khai báo hai lần
- Nút đảo chiều đưa kết quả vừa sinh ngược lại ô nhập để kiểm tra vòng tròn
- Toàn bộ chạy trong trình duyệt, không gửi tệp cấu hình đi đâu
Vì sao tệp cấu hình lại hay phải đổi qua lại giữa ba định dạng
Một dự án thật hiếm khi chỉ dùng một định dạng cấu hình. Phần phụ thuộc của Rust nằm trong Cargo.toml, phần đóng gói của Python hiện đại nằm trong pyproject.toml, còn quy trình chạy tự động lại viết bằng YAML, và mọi thứ chạm tới giao diện lập trình thì trả về JSON. Khi bạn cần đọc một giá trị từ tệp TOML bằng đoạn mã chỉ biết JSON, hoặc cần chép cấu trúc của một tệp YAML sang TOML để đưa vào công cụ khác, việc gõ tay lại toàn bộ vừa mất thời gian vừa dễ nhầm ở đúng chỗ khó nhìn nhất là tầng lồng nhau. Đổi bằng máy giữ nguyên cấu trúc cây, để bạn tập trung vào phần cần sửa. Quan trọng hơn, khi nhìn cùng một dữ liệu ở cả ba dạng, bạn thấy ngay chỗ mình hiểu sai cấu trúc: một khối tưởng là danh sách hóa ra là bảng con, hay ngược lại.
Lợi ích khi sử dụng
- Không cần cài thư viện phân tích TOML chỉ để đọc thử một tệp cấu hình
- Nhìn cùng một cấu trúc ở ba dạng giúp phát hiện ngay chỗ hiểu sai tầng lồng nhau
- Thông báo lỗi kèm số dòng nên sửa được ngay thay vì mò từ đầu tệp
- Bảng nội tuyến và mảng bảng được giữ đúng hình dạng khi quay lại TOML
- Dữ liệu cấu hình có thể chứa chuỗi kết nối và khóa nội bộ nên việc chạy hoàn toàn trên máy bạn là điều kiện bắt buộc
Cách dùng bộ chuyển đổi TOML
- 1Chọn định dạng nguồn ở ô bên trái theo đúng nội dung bạn sắp dán vào, TOML, JSON hay YAML.
- 2Chọn định dạng đích ở ô bên phải, hoặc bấm nút hai mũi tên để đảo nhanh hai đầu.
- 3Dán nội dung vào ô lớn bên trái, hoặc bấm nạp ví dụ TOML để xem trước một tệp cấu hình đủ các thành phần.
- 4Bấm chuyển đổi, đọc kết quả ở ô bên phải cùng dòng ghi chú về những gì không giữ nguyên được.
- 5Nếu có lỗi, đọc số dòng trong thông báo rồi sửa đúng dòng đó, phần lớn lỗi TOML nằm ở dấu bằng, dấu đóng ngoặc hoặc khóa trùng.
TOML dựng cấu trúc bằng bảng chứ không bằng thụt lề
Điểm khác biệt gốc rễ giữa TOML và YAML nằm ở cách đánh dấu tầng. YAML dùng số dấu cách ở đầu dòng, còn TOML dùng tiêu đề bảng đặt trong ngoặc vuông, nên một dòng TOML bất kỳ vẫn hiểu được dù bạn cắt nó ra khỏi ngữ cảnh. Tiêu đề dạng một cặp ngoặc vuông mở ra một bảng, mọi cặp khóa giá trị viết bên dưới thuộc về bảng đó cho tới tiêu đề kế tiếp. Dấu chấm trong tiêu đề tạo tầng lồng, nên bảng viết là a chấm b tương đương với một đối tượng b nằm trong đối tượng a khi đổi sang JSON. Tiêu đề dạng hai cặp ngoặc vuông thì khác hẳn: mỗi lần nó xuất hiện là một phần tử mới được thêm vào một mảng, nên viết nó ba lần sẽ cho ra mảng ba đối tượng. Đây là chỗ người mới hay nhầm, vì hai cặp ngoặc trông chỉ như một biến thể trang trí. Ngoài ra còn bảng nội tuyến viết trong ngoặc nhọn cho các nhóm ngắn gọn trên một dòng, và khóa chấm cho phép gán thẳng vào tầng sâu mà không cần mở tiêu đề riêng. Bốn cách viết này khi đổi sang JSON đều quy về hai kiểu duy nhất là đối tượng và mảng.
Bốn kiểu thời gian của TOML và chỗ dữ liệu bị mòn khi sang JSON
TOML là một trong số ít định dạng cấu hình có kiểu thời gian thật sự trong đặc tả, gồm bốn dạng. Thứ nhất là mốc thời gian có độ lệch múi giờ, ví dụ ngày tháng năm nối chữ T rồi giờ phút giây kèm chữ Z hoặc kèm dấu cộng trừ với hai số. Thứ hai là mốc thời gian cục bộ, viết y hệt nhưng bỏ phần độ lệch, nghĩa là nó không gắn với múi giờ nào cả. Thứ ba là ngày cục bộ, chỉ có ngày tháng năm. Thứ tư là giờ cục bộ, chỉ có giờ phút giây. Bộ đọc ở đây nhận cả bốn dạng, đồng thời chấp nhận dấu cách thay cho chữ T như đặc tả cho phép. Vấn đề nằm ở đầu ra: JSON không có kiểu thời gian, chỉ có chuỗi, số, đúng sai, rỗng, mảng và đối tượng. Vì vậy mọi giá trị thời gian khi sang JSON đều thành chuỗi, và thông tin rằng nó vốn là một mốc thời gian bị mất. Để chiều ngược lại vẫn dùng được, bộ ghi TOML nhận diện chuỗi có hình dạng ngày giờ chuẩn rồi ghi lại chúng không bọc nháy. Cách này giúp vòng tròn TOML sang JSON rồi về TOML cho ra đúng tệp ban đầu, nhưng cũng có mặt trái cần biết: một chuỗi vốn dĩ chỉ là chuỗi mà tình cờ trông giống ngày tháng, chẳng hạn mã lô hàng viết theo dạng năm tháng ngày, sẽ bị nâng thành kiểu thời gian khi quay về TOML. Nếu tệp của bạn có loại giá trị đó, hãy kiểm tra lại thủ công sau khi chuyển.
Những thứ không đi qua được phép chuyển đổi
Mọi bộ chuyển đổi định dạng đều làm việc trên cây dữ liệu chứ không trên văn bản, nên phần trang trí của văn bản gốc biến mất. Thứ đầu tiên là chú thích. Một tệp cấu hình tốt thường có nửa số dòng là lời giải thích vì sao đặt giá trị này, và toàn bộ phần đó không tồn tại trong cây dữ liệu nên không thể sinh lại. Hãy giữ tệp gốc thay vì thay thế nó bằng bản đã chuyển. Thứ hai là cách viết số. Dấu gạch dưới ngăn nhóm trong một nghìn, tiền tố không x của số hệ mười sáu, tiền tố không o của hệ tám đều chỉ là cách viết cho người đọc dễ nhìn, còn giá trị lưu trong bộ nhớ vẫn là một con số. Vì vậy một nghìn viết có gạch dưới sẽ trở về dạng bốn chữ số liền, và số hệ mười sáu trở về dạng thập phân. Thứ ba là thứ tự và cách gom nhóm khóa. Bộ ghi luôn xuất các giá trị đơn của một bảng trước rồi mới tới các bảng con, nên nếu tệp gốc của bạn xen kẽ hai loại này thì bản mới sẽ gom lại khác đi, dù dữ liệu không đổi. Thứ tư là giá trị rỗng. TOML cố ý không có khái niệm rỗng, một khóa hoặc có giá trị hoặc không tồn tại. Khi JSON của bạn chứa giá trị rỗng, bộ ghi buộc phải thay bằng chuỗi trống, và đó là mất mát ngữ nghĩa thật sự, nên với những trường như vậy hãy tự quyết định là bỏ hẳn khóa đi hay dùng một giá trị quy ước.
Ba định dạng, ba mục đích, và ranh giới với các công cụ khác trên site
TOML sinh ra để người viết tay tệp cấu hình, nên nó ưu tiên sự rõ ràng và khả năng đọc từng dòng độc lập, đổi lại nó không phù hợp để biểu diễn dữ liệu lồng sâu nhiều tầng vì tiêu đề bảng sẽ dài lê thê. JSON sinh ra để máy trao đổi với máy, nên cú pháp chặt, không chú thích, không phần thừa, và mọi ngôn ngữ đều có sẵn bộ đọc. YAML sinh ra để viết cấu hình dài có nhiều danh sách lồng nhau, mạnh về thụt lề và các khối văn bản dài, nhưng chính sự linh hoạt đó làm nó dễ sai. Nếu việc bạn cần chỉ là qua lại giữa JSON và YAML thì trang chuyên cho cặp đó nằm ở /vi/tools/json-yaml. Nếu bạn cần làm đẹp, kiểm tra tính hợp lệ hay nén một khối JSON thì dùng /vi/tools/json-formatter. Nếu bạn phải xử lý tệp cấu hình có chú thích và dấu phẩy thừa kiểu tsconfig thì đó là công việc của /vi/tools/json5-converter chứ không phải trang này. Muốn đổi JSON sang bảng biểu hay câu lệnh cơ sở dữ liệu thì xem /vi/tools/json-converter, còn muốn sinh khai báo kiểu cho ngôn ngữ lập trình từ JSON thì có /vi/tools/json-to-typescript, /vi/tools/json-to-go-struct và /vi/tools/json-to-python-dataclass. Trang bạn đang xem chỉ làm đúng một việc là dịch qua lại ba định dạng cấu hình, không định dạng lại, không kiểm định lược đồ và không sinh mã.
Bẫy quen thuộc khi viết YAML và phạm vi bộ đọc YAML ở đây
Bộ đọc YAML trong công cụ này bao được phần cú pháp mà tệp cấu hình đời thường hay dùng: ánh xạ khối, dãy khối, dãy lồng trong ánh xạ, chuỗi khối với dấu sổ đứng và dấu lớn hơn kèm dấu trừ cắt dòng trống cuối, dạng dòng đơn viết trong ngoặc vuông và ngoặc nhọn, chú thích, ba gạch mở tài liệu. Ba thứ chưa hỗ trợ là neo cùng tham chiếu, thẻ kiểu tường minh, và nhiều tài liệu trong một tệp. Bên cạnh phạm vi, có vài cái bẫy của chính YAML mà bạn nên biết. Cái nổi tiếng nhất là các từ trông như chữ nhưng bị hiểu thành đúng sai: chữ no viết trần bị đọc thành sai, chữ yes bị đọc thành đúng, và mã quốc gia của Na Uy viết trần cũng rơi vào bẫy này. Cách tránh là bọc nháy cho mọi chuỗi có nguy cơ. Cái thứ hai là số phiên bản: ba chấm mười viết trần thành số ba phẩy một, mất chữ số cuối, nên phiên bản luôn phải bọc nháy. Cái thứ ba là dấu tab, YAML cấm dùng tab để thụt lề và nhiều trình soạn thảo lại chèn tab mặc định. Cái thứ tư là dấu hai chấm nằm giữa câu trong một giá trị không bọc nháy, nó khiến bộ đọc tưởng đây là cặp khóa giá trị mới. Khi ghi ra YAML, công cụ chủ động bọc nháy cho các chuỗi rơi vào những trường hợp trên để bản sinh ra đọc lại được đúng như cũ.
Câu hỏi thường gặp (FAQ)
Hai cặp ngoặc vuông trong TOML khác một cặp ở chỗ nào?
Một cặp ngoặc vuông mở một bảng, tương đương một đối tượng trong JSON, và chỉ được viết một lần cho mỗi đường dẫn. Hai cặp ngoặc vuông thêm một phần tử vào mảng, nên viết ba lần cùng một tên sẽ cho ra mảng ba đối tượng. Đây là cách duy nhất trong TOML để tạo danh sách các nhóm cấu hình nhiều dòng.
Vì sao số một nghìn viết có dấu gạch dưới lại trở về dạng bốn chữ số liền?
Dấu gạch dưới chỉ là cách viết cho dễ nhìn, đặc tả TOML quy định nó bị bỏ qua khi đọc giá trị. Trong bộ nhớ chỉ còn con số một nghìn, không có thông tin nào ghi lại rằng bạn từng đặt gạch dưới ở đâu. Số hệ mười sáu và hệ tám cũng vậy, chúng trở về dạng thập phân sau khi chuyển.
Chuyển từ JSON có giá trị rỗng sang TOML thì kết quả ra sao?
TOML cố ý không định nghĩa giá trị rỗng, quan điểm của đặc tả là một khóa hoặc có giá trị hoặc không nên tồn tại. Công cụ buộc phải thay bằng chuỗi trống để bản sinh ra vẫn hợp lệ. Đây là mất mát ngữ nghĩa thật, nên hãy tự quyết định bỏ hẳn khóa đó hay dùng một giá trị quy ước có ý nghĩa với ứng dụng của bạn.
Chú thích trong tệp cấu hình có được giữ lại không?
Không. Bộ chuyển đổi làm việc trên cây dữ liệu sau khi đọc, mà chú thích không phải là dữ liệu nên nó biến mất ngay ở bước đọc. Hãy giữ tệp gốc thay vì thay thế bằng bản đã chuyển, và nếu bắt buộc phải thay thì chép lại phần chú thích bằng tay sau khi chuyển.
Mốc thời gian có giữ nguyên khi đi vòng TOML sang JSON rồi quay lại không?
Có, vì bộ ghi nhận diện chuỗi mang hình dạng ngày giờ chuẩn rồi ghi lại chúng không bọc nháy, đúng như kiểu thời gian của TOML. Mặt trái là một chuỗi vốn chỉ là chuỗi mà tình cờ trông giống ngày tháng cũng bị nâng thành kiểu thời gian, nên hãy kiểm tra lại nếu tệp của bạn có mã số viết theo dạng năm tháng ngày.
Bảng nội tuyến có bị bung thành tiêu đề riêng không?
Không, nếu bảng đó nhỏ. Bộ ghi giữ nguyên dạng nội tuyến cho các bảng có tối đa bốn khóa, chỉ chứa giá trị đơn và viết ra không quá bảy mươi hai ký tự. Vượt ngưỡng đó thì nó được tách thành một tiêu đề bảng riêng để dòng không quá dài và vẫn hợp lệ.
Vì sao thứ tự khóa sau khi chuyển khác tệp gốc của tôi?
Bộ ghi luôn xuất các giá trị đơn của một bảng trước, rồi mới tới các bảng con và các mảng bảng. Nếu tệp gốc xen kẽ hai loại này thì bản mới gom lại khác đi. Dữ liệu không thay đổi, chỉ cách sắp xếp thay đổi, và đây là điều bắt buộc vì trong TOML mọi cặp khóa giá trị viết sau một tiêu đề đều thuộc về bảng đó.
Bộ đọc YAML ở đây có hiểu neo và tham chiếu không?
Chưa. Ba thứ nằm ngoài phạm vi là neo cùng tham chiếu, thẻ kiểu tường minh, và nhiều tài liệu ngăn nhau bằng ba gạch trong cùng một tệp. Nếu tệp YAML của bạn dùng chúng, hãy khai triển thủ công phần dùng lại trước khi dán vào, hoặc chuyển từ JSON sang thay vì từ YAML.
Vì sao giá trị no trong YAML của tôi lại thành sai?
Vì YAML coi một loạt từ viết trần là giá trị đúng sai, trong đó có no, yes, on, off. Mã quốc gia của Na Uy cũng rơi vào bẫy này. Cách chữa duy nhất là bọc nháy cho chuỗi. Khi ghi ra YAML, công cụ tự bọc nháy các chuỗi rơi vào nhóm nguy hiểm để bản sinh ra đọc lại đúng như cũ.
Dán một mảng ở tầng gốc rồi chuyển sang TOML thì báo lỗi, vì sao?
Vì TOML quy định tầng gốc của tài liệu luôn là một bảng, không thể là mảng. Cách xử lý là bọc mảng của bạn vào một khóa, ví dụ đặt tên là items, rồi chuyển lại. Khi đó mỗi phần tử sẽ thành một khối tiêu đề hai cặp ngoặc vuông.
Tệp Cargo.toml hay pyproject.toml dán vào có chạy được không?
Được, đó chính là loại tệp bộ đọc này nhắm tới. Chúng dùng bảng lồng, mảng bảng cho danh sách phụ thuộc, bảng nội tuyến cho các khai báo ngắn và chuỗi nhiều dòng cho phần mô tả. Chỉ lưu ý là toàn bộ chú thích trong tệp sẽ không có trong bản đã chuyển.
Nội dung tôi dán vào có được gửi lên máy chủ không?
Không. Bộ đọc và bộ ghi cho cả ba định dạng đều viết bằng JavaScript chạy trong trình duyệt, không có bước gọi mạng nào. Nhờ vậy bạn dán được tệp cấu hình thật, kể cả khi trong đó có chuỗi kết nối cơ sở dữ liệu hay tên máy chủ nội bộ.
Từ khóa liên quan
- toml converter
- chuyển toml sang json
- đổi json sang toml
- toml sang yaml online
- toml là gì
- cú pháp toml
- array of tables toml
- inline table toml
- kiểu ngày giờ trong toml
- cargo toml là gì
- pyproject toml
- so sánh toml yaml json
- định dạng file cấu hình
- toml có null không
- lỗi cú pháp toml
- đọc file toml online
- yaml bị hiểu sai giá trị no
- công cụ chuyển đổi cấu hình
- chuyển đổi toml miễn phí
- toml parser trên trình duyệt
