เครื่องมือสำหรับนักพัฒนา · ตัวแปลงไวยากรณ์
วิธีที่ตาราง TOML กลายเป็นวัตถุ JSON: [table], [[array]] และคีย์จุด
· มันทำงานอย่างไร
ทอมล์ json ข้อมูลรูปแบบ
ส่วนหัวของ TOML ดูไม่มีอะไรเหมือนกับเครื่องหมายปีกกาของ JSON แต่กำหนดให้มีการซ้อนกันทุกประการ โพสต์นี้จะอธิบายว่า [server], [[products]] และ a.b.c แมปกับอ็อบเจ็กต์และอาร์เรย์ JSON ได้อย่างไร และตำแหน่งที่ทั้งสองโมเดลแตกต่างกัน
การทำรังมาจากไหน? — ไฟล์ TOML ที่ดูเรียบๆ ถูกแปลงเป็น JSON ที่ซ้อนกันลึก และส่วนหัวที่ทำให้เกิดไฟล์นั้น
ไฟล์ TOML สามารถปรากฏได้เกือบแบนเนื่องจากวงเล็บเหลี่ยมมีการซ้อน `[a.b.c]` เปิดตารางระดับกลาง ดังนั้น `d = 1` ที่อยู่ด้านล่างจะกลายเป็น `{"a":{"b":{"c":{"d":1}}}}` วงเล็บปีกกา JSON ทำให้เห็นลำดับชั้นที่ TOML แสดงออกผ่านเส้นทางตารางที่ใช้งานอยู่
ToolAcre มอบสิทธิ์การแยกวิเคราะห์ไวยากรณ์เป็น smol-toml จากนั้นทำให้ค่า JSON กลับสู่ปกติไม่สามารถดำเนินการได้ นี่ไม่ใช่การเขียนใหม่โดยใช้บรรทัด ตาราง คีย์จุด และอาร์เรย์ของตารางกลายเป็นอ็อบเจ็กต์และอาร์เรย์ธรรมดาก่อน JSON การทำให้เป็นอนุกรม ซึ่งเป็นสาเหตุที่ทำให้การสะกดและความคิดเห็นของตารางไม่สามารถใช้งานได้ในเอาต์พุต
ส่วนหัวของ [table] — วิธีที่ส่วนหัวเปิดวัตถุที่ซ้อนกัน และวิธีที่ [a.b.c] สร้างวัตถุระดับกลางโดยปริยาย
ส่วนหัวของวงเล็บปีกกาเดียวจะเปิดตาราง `[owner]` กำหนดการดำเนินการต่อไปนี้ให้กับ `owner`; `[owner.contact]` สร้างหรือเข้าสู่วัตถุผู้ติดต่อที่ซ้อนกัน ออบเจ็กต์ระดับกลางไม่จำเป็นต้องมีส่วนหัวแยกกัน การมีอยู่ของพวกมันตามมาจากส่วนของเส้นทางในส่วนหัว
การมอบหมายก่อนส่วนหัวใดๆ จะยังคงอยู่ที่ราก ตารางต่อมาจะไม่ย้ายรายการย้อนหลัง เมื่อตรวจสอบ JSON ที่แปลงแล้ว ให้ปฏิบัติตามเส้นทางคุณสมบัติแบบเต็ม แทนที่จะใช้ระยะห่างทางกายภาพระหว่างบรรทัด: ตารางปัจจุบันของ TOML ยังคงทำงานอยู่จนกว่าส่วนหัวอื่นจะเปลี่ยนแปลง
[[array of tables]] - เหตุใดส่วนหัวของวงเล็บคู่ที่ซ้ำกันจึงผนวกวัตถุเข้ากับอาร์เรย์และลำดับที่รักษาไว้
ส่วนหัวแบบวงเล็บคู่จะผนวกตารางเข้ากับอาร์เรย์ `[[server]]` สองส่วนกลายเป็น `server: [{...},{...}]` ตามลำดับแหล่งที่มา ช่องใต้แต่ละส่วนหัวเป็นของสมาชิกอาร์เรย์นั้นจนกว่าส่วนหัวอื่นจะเริ่มต้นขึ้น ทำให้การกำหนดค่าซ้ำมีความชัดเจนใน JSON
ลำดับภายในอาเรย์คือข้อมูลและถูกเก็บรักษาไว้ การนำเสนอคีย์ออบเจ็กต์อาจถูกจัดเรียงในภายหลังเมื่อเลือกตัวเลือก แต่สมาชิกอาร์เรย์จะไม่เรียงลำดับใหม่ การทำให้ทั้งสองสับสนจะเปลี่ยนลำดับความสำคัญของเซิร์ฟเวอร์หรือลำดับปลั๊กอิน แทนที่จะเพียงจัดรูปแบบเอกสาร
ปุ่มประและตารางอินไลน์ — a.b = 1 และ { x = 1 } เป็นอีกสองวิธีในการแสดงการซ้อนแบบเดียวกัน
การมอบหมายแบบจุดให้สัญลักษณ์เส้นทางอื่น: `a.b.c = true` ให้ผลลัพธ์รูปร่างของวัตถุที่ซ้อนกันเหมือนกับส่วนหัวของตารางที่สอดคล้องกัน ตารางอินไลน์ เช่น `point = { x = 1, y = 2 }` จะกลายเป็นอ็อบเจ็กต์ที่ซ้อนกันทันที แบบฟอร์มเหล่านี้สามารถอธิบายต้นไม้ที่คล้ายกันในขณะที่ดูแตกต่างอย่างมากสำหรับผู้ตรวจสอบ
JSON บันทึกเฉพาะคีย์และค่าผลลัพธ์ ไม่ใช่สัญกรณ์ TOML ใดที่เขียนขึ้น การแปลงกลับจึงไม่สามารถคืนค่าตัวเลือกเดิมระหว่างส่วนหัว คีย์จุด และตารางอินไลน์ได้ ผู้เขียน TOML เลือกการทำให้เป็นอนุกรมที่ถูกต้องของตัวเองจากแผนผัง
ประเภทที่ยกมาและประเภทที่ไม่มีการแมป - จำนวนเต็ม ทศนิยม บูลีน และสตริงโดยตรง วันที่-เวลากลายเป็นสตริงและ JSON null ไม่มีแหล่งที่มา TOML
สตริง จำนวนเต็มปลอดภัย ทศนิยม บูลีน อาร์เรย์ และตารางแมปโดยตรง ประเภทชั่วคราวสี่ประเภทของ TOML ไม่ได้: ออฟเซ็ตวันที่-เวลา, วันที่-เวลาท้องถิ่น, วันที่ท้องถิ่น และเวลาท้องถิ่น จะกลายเป็น RFC 3339-สตริงแหล่งที่มาที่เหมือนกัน และคำเตือนจะตั้งชื่อแต่ละเส้นทางและประเภท ผู้เขียนเสนอราคาสตริงเหล่านั้นในภายหลังแทนที่จะสร้างโทเค็นวันที่และเวลาขึ้นใหม่
จำนวนเต็ม 64 บิตที่ลงนามของ TOML สามารถเกินช่วงจำนวนเต็มที่ปลอดภัยของ JavaScript ได้ smol-toml ส่งคืนค่าเช่น BigInt เมื่อจำเป็น ToolAcre แปลงเป็นสตริงทศนิยมและเตือนแทนที่จะปัดเศษตัวเลข วิธีนี้จะรักษาการสะกดไว้โดยไม่ต้องเปลี่ยนประเภท JSON
ตัวอย่างการทำงาน: รายการ pyproject.toml — [project], [project.optional-dependencies] และ [[tool.plugins]] แปลงเป็น JSON โดยมีการติดตามแต่ละระดับ
ลองใช้ `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]` จากนั้น `[[tool.plugins]]` สองตารางที่มีชื่อแตกต่างกัน JSON วางชื่อไว้ที่รูท ซ้อนโปรเจ็กต์และเป็นทางเลือก และสร้างอาร์เรย์ปลั๊กอินใต้เครื่องมือ
เพิ่ม `released = 1979-05-27` และ `huge = 9223372036854775807` อันแรกจะกลายเป็นสตริง `1979-05-27`; ส่วนที่สองจะกลายเป็นสตริงทศนิยม คำเตือนทั้งสองระบุเส้นทางที่เปลี่ยนแปลง ทำให้ประเภท non-JSON สามารถตรวจสอบได้ แทนที่จะอนุญาตให้มีการบังคับวันที่หรือตัวเลขแบบเงียบ
สิ่งนี้ไม่ครอบคลุมถึง — การแปลง JSON กลับเป็นสำนวน TOML ด้วยการจัดกลุ่มส่วนหัวที่สมเหตุสมผล ซึ่งเกี่ยวข้องกับการเลือกสไตล์ที่ไม่มีกฎใดกำหนดได้ครบถ้วน
JSON-to-TOML ได้รับการสนับสนุนสำหรับออบเจ็กต์รูท แต่ไม่ได้สร้างตัวเลือกหรือความคิดเห็นของผู้เขียนที่เป็นสำนวนขึ้นมาใหม่ ละเว้นคีย์ที่มีค่า Null ค่าว่างภายในอาร์เรย์จะกลายเป็นสตริงว่างเพื่อรักษาตำแหน่งไว้ อาร์เรย์รูท สเกลาร์ หรือค่าว่างถูกปฏิเสธ เนื่องจากเอกสาร TOML ต้องเป็นตาราง
พฤติกรรมดังกล่าวจะแก้ไขนัยของโครงร่างที่ว่าการแปลงแบบย้อนกลับอยู่นอกขอบเขต ตัวแปลงเขียน TOML แต่ความเที่ยงตรงของสไตล์อยู่นอกเหนือสัญญา ความแตกต่างมีความสำคัญ: การทำให้เป็นซีเรียลไลซ์ที่ได้รับการสนับสนุนนั้นไม่เหมือนกับการกู้คืนไบต์ของไฟล์ต้นฉบับต่อไบต์หรือการเลือกเค้าโครงที่ผู้ดูแลต้องการ
รองรับการเขียน JSON กลับไปที่ TOML แต่ความคิดเห็น ประเภทวันที่เวลา และรูปแบบการอนุญาตจะไม่ส่งคืน
อ่านส่วนหัว TOML เป็นเส้นทางและวงเล็บคู่เมื่อผนวกการดำเนินการ มุมมอง JSON มีประโยชน์สำหรับการติดตามแผนผังผลลัพธ์ ในขณะที่คำเตือนเปิดเผยวันที่และเวลาและจำนวนเต็มกว้างที่ข้ามขอบเขตประเภท อย่าเรียกการดำเนินการแบบไม่สูญเสียเมื่อมีคำเตือนปรากฏขึ้น
สำหรับการย้ายการกำหนดค่า ให้เก็บต้นฉบับไว้ข้างเอาต์พุตที่แปลงแล้ว ตรวจสอบค่าก่อน จากนั้นแก้ไของค์กร TOML สำหรับผู้อ่านและเครื่องมือเป้าหมาย ตัวแปลงไวยากรณ์ดำเนินการขั้นตอนการแยกวิเคราะห์และเขียนแบบกลไก ไม่สามารถตัดสินใจได้ว่าการจัดกลุ่มเฉพาะโครงการ คีย์ที่ยอมรับ หรือว่าแอปพลิเคชันรองรับไฟล์นั้นหรือไม่
การเปรียบเทียบขั้นสุดท้ายควรแยกคำถาม 3 ข้อที่เบลอได้ง่ายออกจากกัน ประการแรก ค่าที่แยกวิเคราะห์ยังคงอยู่หรือไม่ ประการที่สอง TOML-ประเภทใด ๆ กลายเป็นสตริง JSON หรือมีค่าว่างใด ๆ หายไปหรือไม่ ประการที่สาม TOML ที่ได้รับอนุกรมใหม่ได้รับการจัดระเบียบในลักษณะที่ผู้ดูแลสามารถเข้าใจได้หรือไม่ สองรายการแรกสามารถตรวจสอบกับค่าและคำเตือนได้ ส่วนที่สามต้องได้รับการตรวจสอบจากเจ้าหน้าที่ การแยกเช็คเหล่านั้นออกจากกันจะป้องกันไม่ให้การซีเรียลไลเซชันที่ถูกต้องทางเทคนิคถูกเรียกว่าการโยกย้ายที่ซื่อสัตย์ เมื่อประเภทหรือโครงสร้างการอนุญาตมีการเปลี่ยนแปลง