เครื่องมือสำหรับนักพัฒนา · ตัวแปลงไวยากรณ์
การย้ายการกำหนดค่า JSON ไปยัง TOML: อะไรทำให้เกิดการเปลี่ยนแปลงและอะไรที่ต้องการมนุษย์
· เหตุใดจึงสำคัญ
json ทอมล์ นักพัฒนาเวิร์กโฟลว์
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 ที่สร้างขึ้นเพียงอย่างเดียวไม่สามารถอธิบายให้ผู้ดูแลคนต่อไปได้