ไทย

เครื่องมือสำหรับนักพัฒนา · ตัวแปลงไวยากรณ์

การย้ายการกำหนดค่า JSON ไปยัง TOML: อะไรทำให้เกิดการเปลี่ยนแปลงและอะไรที่ต้องการมนุษย์

· เหตุใดจึงสำคัญ

เผยแพร่โดย ToolAcre บทวิจารณ์เพิ่มเติม

json ทอมล์ นักพัฒนาเวิร์กโฟลว์

ค่า JSON ย้ายเข้าสู่ TOML ในขณะที่ค่าว่างถูกตั้งค่าสถานะและลบออก
ภาพประกอบเวกเตอร์ต้นฉบับ ToolAcre

TOML ได้กลายเป็นรูปแบบการกำหนดค่าสำหรับโปรเจ็กต์ Python และ Rust และไฟล์การตั้งค่า JSON จำนวนมากกำลังย้ายไปอยู่ โพสต์นี้อธิบายว่าส่วนใดที่แปลงโดยกลไกและส่วนใด (ค่าว่าง, อาร์เรย์แบบผสม, การซ้อนแบบลึก) ต้องมีการพิจารณา

ยุค setup.cfg และ settings.json กำลังจะสิ้นสุดลง — โปรเจ็กต์ที่รวมการกำหนดค่าเข้ากับ pyproject.toml และบล็อก JSON ที่ต้องย้าย

บางครั้งโปรเจ็กต์จะรวมการตั้งค่าไว้ในไฟล์ TOML ไฟล์เดียว แต่พื้นที่เก็บข้อมูลไม่สามารถรองรับการอ้างสิทธิ์ของโครงร่างที่ว่า "ยุคกำลังจะสิ้นสุด" งานภาคปฏิบัติแคบลง: ย้ายวัตถุที่มีรูปทรง JSON ลงในตาราง TOML ตรวจสอบการสูญเสีย จากนั้นตรวจสอบว่าแอปพลิเคชันเป้าหมายจดจำคีย์ผลลัพธ์ได้จริง

ToolAcre ต้องใช้วัตถุรูทสำหรับเอาต์พุต TOML อาร์เรย์รูท สตริง ตัวเลข บูลีนหรือค่าว่างถูกปฏิเสธเนื่องจากเอกสาร TOML เป็นตาราง การตรวจสอบรูปร่างตั้งแต่เนิ่นๆ จะป้องกันไม่ให้เครื่องห่อที่ประดิษฐ์ขึ้นมีลักษณะเหมือนการกำหนดค่าที่ได้รับการอนุมัติจากแอปพลิเคชัน

การรวมการกำหนดค่าเป็นทางเลือกของโปรเจ็กต์ ไม่ใช่จุดสิ้นสุดสากลของรูปแบบเก่าๆ

ตัวแปลงพิสูจน์กลไกที่เป็นรูปธรรม: TOML มีตาราง อาร์เรย์ และค่าสเกลาร์ ผู้เขียนเปลี่ยนวัตถุที่ซ้อนกันให้เป็นโครงสร้าง TOML ที่ถูกต้อง นอกจากนี้ยังไม่มีค่าว่างและใช้ไวยากรณ์ที่แตกต่างจากเครื่องหมายปีกกา JSON การกล่าวอ้างเกี่ยวกับการตั้งค่าระบบนิเวศหรือความเหนือกว่าของการออกแบบจำเป็นต้องมีแหล่งที่มาภายนอกไฟล์การใช้งานเหล่านี้

ความคิดเห็นเป็นเหตุผลหนึ่งที่ผู้ดูแลอาจต้องการผู้เขียน TOML แต่อินพุต JSON ไม่มีสิ่งใดที่จะส่งต่อ เอกสารที่สร้างขึ้นเป็นค่าเริ่มต้นการทำให้เป็นอนุกรม จะต้องเพิ่มคำอธิบายโดยเจ้าหน้าที่และองค์กรเฉพาะโครงการในภายหลัง

สิ่งที่ตัวแปลงนี้พิสูจน์ได้เกี่ยวกับ TOML มากกว่าการสนับสนุนรูปแบบทั่วไป

สตริง จำนวนจำกัด บูลีน วัตถุที่ซ้อนกัน และอาร์เรย์ที่รองรับโดย smol-toml จะแปลงทางกลไก อาร์เรย์ของวัตถุสามารถกลายเป็นอาร์เรย์ของตารางได้ วัตถุที่ซ้อนกันสามารถกลายเป็นส่วนหัวของตารางได้ Unicode และบรรทัดใหม่ที่ใช้ Escape จะรอดพ้นการทดสอบไปกลับสำหรับค่าปกติ

กฎอาร์เรย์ TOML สามารถปฏิเสธรูปร่างที่ผู้เขียนไม่สามารถแสดงได้ และชื่อข้อผิดพลาดที่ล้มเหลวแทนที่จะบังคับอย่างเงียบๆ การเรียกอาร์เรย์ทั้งหมดที่เป็นเนื้อเดียวกันล่วงหน้าจะทำให้พฤติกรรมที่ทดสอบของการขึ้นต่อกันนั้นง่ายเกินไป ซึ่งอาจอ่านแม้กระทั่งอาร์เรย์ที่ต่างกันด้วยซ้ำ ใช้การแปลงจริงเป็นประตู

สิ่งที่แปลงโดยกลไก รวมถึงอาร์เรย์ที่ผู้เขียน TOML ยอมรับ

Null ไม่มีการเป็นตัวแทน TOML คุณสมบัติอ็อบเจ็กต์ที่มีค่า null จะถูกละเว้นและแสดงอยู่ในคำเตือน ค่าว่างภายในอาร์เรย์จะกลายเป็นสตริงว่าง ดังนั้นดัชนีในภายหลังจึงไม่เปลี่ยน การทดแทนนั้นก็มีชื่อเช่นกัน ผลลัพธ์ทั้งสองจะไม่รักษาคุณค่าดั้งเดิมไว้

ตัดสินใจว่าจะหมายถึงอะไรก่อนที่จะยอมรับการเปลี่ยนแปลงอย่างใดอย่างหนึ่ง อาจหมายถึงการสืบทอดค่าเริ่มต้น ล้างฟิลด์อย่างชัดเจน หรือไม่ระบุค่าใดๆ การลบคีย์หรือการแทนที่ข้อความว่างสามารถเปลี่ยนความหมายของแอปพลิเคชันได้ ดังนั้นให้แก้ไขกับโมเดลการกำหนดค่าที่บันทึกไว้ของปลายทาง

ที่ที่สไตล์ต้องการมนุษย์ — การเลือกระหว่างส่วนหัวของ [ตาราง] ปุ่มจุดและตารางอินไลน์ และการจัดกลุ่มคีย์ที่เกี่ยวข้องเพื่อให้ไฟล์อ่านได้ดี

ทรีไม่ได้บอกว่าผู้ดูแลชอบ `[tool.linter]` คีย์แบบจุด หรือตารางแบบอินไลน์ ตัวซีเรียลไลเซอร์จะเลือกไวยากรณ์ที่ถูกต้อง ในขณะที่มนุษย์เลือกการจัดกลุ่มที่ทำให้ความเป็นเจ้าของและตัวเลือกที่เกี่ยวข้องมีความชัดเจน คีย์การเรียงลำดับสามารถกำหนดเอาต์พุตได้ แต่อาจแยกแนวคิดที่อยู่ด้วยกัน

รักษาส่วนต่างเล็กน้อยและเพิ่มความคิดเห็นหลังจากตรวจสอบค่าแล้ว การแปลง TOML กลับเป็น JSON ในภายหลัง จะไม่สามารถเรียกคืนความคิดเห็นเหล่านั้นหรือการสะกดตารางที่เลือกได้ สไตล์เป็นข้อมูลที่เขียนไว้ภายนอกโมเดลค่าธรรมดา

ตัวอย่างการทำงาน: JSON ของ linter กำหนดค่าเป็น TOML - การแปลง แก้ไขค่าว่างสองค่า และจัดกลุ่มผลลัพธ์ใหม่ภายใต้ส่วนหัว [tool.linter]

แปลง `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}` ยอมรับวัตถุรูทแล้ว `preview` ถูกละไว้; สมาชิกอาร์เรย์ว่างกลายเป็นสตริงว่าง คำเตือนตั้งชื่อทั้งสองเส้นทาง อ็อบเจ็กต์ที่ซ้อนกันที่เหลือจะถูกทำให้เป็นอนุกรมภายใต้ตาราง TOML ที่เลือกโดยผู้เขียน

ก่อนบันทึก ให้ตัดสินใจว่าการแสดงตัวอย่างควรเป็นเท็จ ไม่มี หรือค่าอื่นที่บันทึกไว้ และพิจารณาว่ารายการยกเว้นที่ว่างเปล่านั้นถูกต้องหรือไม่ จากนั้นจัดกลุ่มใหม่และแสดงความคิดเห็นในตารางเพื่อให้ผู้อ่าน ตัวอย่างนี้แสดงให้เห็นว่าเหตุใดการแปลงจึงเป็นกลไกในขณะที่การโยกย้ายเป็นไปตามความหมาย

สิ่งนี้ไม่ครอบคลุม — ว่าเครื่องมือเป้าหมายอ่าน TOML จริงหรือไม่ และชื่อคีย์เฉพาะของมัน ซึ่งมีเพียงเอกสารประกอบเท่านั้นที่สามารถบอกคุณได้

ไฟล์ TOML ที่ถูกต้องไม่ได้พิสูจน์ว่าเครื่องมืออ่าน TOML รู้จักส่วน หรือตีความคีย์เหมือนกับผู้บริโภค JSON แบบเก่า ตรวจสอบเอกสารเป้าหมายปัจจุบันและรันการตรวจสอบความถูกต้องหรือคำสั่ง dry-run ของตัวเอง ToolAcre ไม่เคยนำเข้าสคีมาของแอปพลิเคชัน

วันที่ยังสมควรได้รับการดูแลในทิศทางตรงกันข้าม TOML-ค่าชั่วคราวดั้งเดิมจะกลายเป็นสตริงเมื่ออ่านลงใน JSON ดังนั้นการเดินทางไปกลับในภายหลังจึงเสนอราคา สายการโยกย้ายที่ข้ามทั้งสองทิศทางไม่สามารถเรียกว่าไม่มีการสูญเสียได้

ประเด็นสำคัญ: แปลงก่อน จากนั้นจึงแก้ไขเพื่อให้อ่านง่าย — และวิธีที่แผงตัวแปลงไวยากรณ์ทำหน้าที่ส่วนกลไกในเบราว์เซอร์ของคุณ

แปลงก่อนเพื่อแสดงความไม่เข้ากันทางกลไก จากนั้นแก้ไขเพื่ออรรถศาสตร์และความสามารถในการอ่าน เก็บต้นฉบับ ทบทวนทุกคำเตือน และทดสอบกับเป้าหมายจริง การจัดการแบบไร้ค่าและรูปร่างของรากนั้นเป็นขอบเขตที่ยากลำบาก การจัดโต๊ะเป็นการตัดสินใจออกแบบโดยมนุษย์

ตัวแปลงไวยากรณ์จะลบงานไวยากรณ์ที่ซ้ำกันโดยไม่ต้องสร้างความรู้เกี่ยวกับแอปพลิเคชัน การแบ่งส่วนนั้นทำให้ผลลัพธ์มีประโยชน์: โครงสร้างที่เครื่องจักรผลิตขึ้นเพื่อการตรวจสอบ ตามด้วยตัวเลือกโดยเจตนาในกรณีที่รูปแบบหรือเครื่องมือไม่ตรงกัน

เก็บบันทึกการย้ายสำหรับทุกคำเตือนที่คุณยอมรับ ถ้าค่าว่างกลายเป็นการขาด ให้ระบุค่าเริ่มต้นปลายทางที่ทำให้การขาดหายไปถูกต้อง หากสมาชิกอาร์เรย์ว่างกลายเป็นข้อความว่างเปล่า ให้อธิบายว่าเหตุใดดัชนีจึงมีความสำคัญ และเหตุใดข้อความว่างจึงถูกต้อง หากผู้เขียนปฏิเสธอาร์เรย์แบบผสม ให้ออกแบบค่านั้นใหม่แทนที่จะบังคับเป็นแบบส่วนตัว การตัดสินใจเหล่านี้เป็นบันทึกการย้ายถิ่นที่คงทน TOML ที่สร้างขึ้นเพียงอย่างเดียวไม่สามารถอธิบายให้ผู้ดูแลคนต่อไปได้