JSON ל-TOML: המר קבצי תצורה בדרך הנכונה

בפעם הראשונה TOML נשך אותי, זה לא היה התחביר זה היה ההזמנה היה לי אובייקט הגדרות JSON משירות Node ישן, רציתי את זה בתור א config.toml לשכתוב של חלודה, ועשיתי מה שכולם עושים בפעם הראשונה: הקלדתי ביד את השולחנות עשר דקות לאחר מכן המנתח זרק שגיאה שלא הבנתי, והצביע על קו שנראה בסדר גמור הבעיה הייתה שלושה מפתחות שישבו מתחת ל-א [table] כותרת שהייתה שייכת מעליה ל-TOML יש כלל ש-JSON לא, וברגע שאתה מועד עליו אתה אף פעם לא שוכח אותו.

אני בונה Toolz.dev, ושלחתי לשם מדף ארוך של ממירי פורמטים, אז כתבתי את הממיר JSON ל-TOML כדי להסיר את כל הקטגוריה הזו של טעות. אתה מדביק את JSON, אתה מקבל TOML שמנתח מחדש לאותם נתונים, וההזמנה מטופלת עבורך. המדריך הזה הוא הדבר שהלוואי שהייתי קורא באותו אחר הצהריים: מה זה TOML, איפה JSON ו-TOML לא מסכימים, ואיך להמיר ביניהם מבלי לאבד שום דבר שאכפת לך ממנו.

TL;DR: TOML הוא פורמט תצורה מוקלד המשמש את Cargo, Poetry, Hugo והרבה כלי עבודה של Rust and Go. המרת JSON ל-TOML היא בעיקר מכנית, אבל שלושה דברים זקוקים לשיפוט: סדר טבלאות (מפתחות לפני טבלאות משנה, תמיד), איך אתה כותב מערכים של אובייקטים (מערכים של טבלאות לעומת טבלאות מוטבעות), ומה קורה ל-JSON null, אשר TOML אין דרך להביע. ה ממיר JSON ל-TOML הופך את שלושתם למפורשים ופועל כולו בדפדפן שלך.

מה זה TOML, ולמה שאמיר את JSON לזה?

TOML מייצג Tom's ברור, שפה מינימלית. זה נקרא כמו קובץ INI ישן, אבל בניגוד ל-INI יש לו מפרט אמיתי עם ערכים מוקלדים, תאריכים מהשורה הראשונה ודקדוק מוגדר. המפרט הזה הוא הסיבה שהוא זכה: פורמט תצורה שאדם יכול לקרוא במבט חטוף, שמכונה מנתחת באותו אופן בכל פעם, ללא אי בהירות אם port = 8080 הוא מחרוזת או מספר זה מספר, כי TOML אומר זאת.

אתה מושיט יד להמרת JSON ל-TOML כאשר מכונה נתנה לך JSON וכלי רוצה TOML. זה קורה יותר ממה שהיית חושב. API מחזיר כתם הגדרות בתור JSON ואתה צריך אותו pyproject.toml. יש לך זקן config.json ואתה מעביר את הפרויקט לערימה שקוראת config.toml. יצרת כמה נתונים באופן פרוגרמטי, זה יצא בתור JSON כי זה מה JSON.stringify מייצרת, והצרכן הוא Cargo או Hugo או שירות Go באמצעות ספריית TOML.בכל מקרה הנתונים זהים רק הסידרה שונה.

הכיוון ההפוך קיים גם, אבל זו עבודה אחרת. אם אתה הולך לכיוון השני, ה פורמט JSON שווה להיות פתוח לשפיות - בדוק תחילה את ה-JSON ואת ממיר JSON ל-YAML מכסה את פורמט התצורה הנפוץ האחר. מדריך זה עוסק ב-JSON שנכנס ל-TOML.

כיצד ממפה הממיר את JSON ל-TOML?

יש רק קומץ צורות ב-JSON, ולכל אחת יש בית ב-TOML. הבנת המיפוי היא רוב הבנת הכלי.

ג'ייסון אובייקט הופך ל-TOML שולחן. האובייקט ברמה העליונה הוא טבלת השורש, וזו הסיבה שהממיר מתעקש שהקלט יהיה אובייקט. אובייקטים מקוננים הופכים [table] כותרות עם נתיב מנוקד, אז { "database": { "pool": { "max": 10 } } } הופך ל [database.pool] סעיף עם max = 10 בתוך זה.

ג'ייסון מערך אובייקטים הופך ל-TOML מערך טבלאות, כתוב בסוגריים הכפולים [[name]] כותרת, בלוק אחד לכל אלמנט זהו דפוס TOML האידיומטי עבור רשימת רשומות: רשימת שרתים, רשימת תלות, רשימת יעדי בנייה כל אלמנט מקבל משלו [[servers]] בלוק.

כל סקלר מפות ישירות מחרוזת JSON הופכת למחרוזת בסיסית של TOML במירכאות כפולות, עם תווי בקרה שנמלטו מספר JSON הופך למספר שלם של TOML אם הוא מספר שלם וצף אחרת. בוליאני של JSON הופך true או false. אלו המקרים הקלים, והממיר אף פעם לא טועה בהם.

ג'ייסון מערך סקלרים הופך למערך מוטבע של TOML: ["admin", "editor"] נשאר ["admin", "editor"]. מערכים מעורבים ומערכים מקוננים נכתבים גם בשורה, כי זה המקום היחיד שהם מתאימים.

מדוע סדר מפתחות משנה כל כך ב-TOML?

זה הכלל שתופס את כולם, אז כדאי לציין זאת בצורה ברורה. ב-TOML, בתוך כל טבלה, כל הטבלה ' צמדי מפתח/ערך משלו חייבים להופיע לפני כל אחת מכותרות המשנה שלו. אם אתה כותב א [server] כותרת, אחר כך כמה מקשים, ואז מקש אחר ששייך לטבלת השורש, המנתח קורא את המקש התועה הזה כחלק ממנו [server] במקום זאת. במקרה הטוב הוא נוחת במקום הלא נכון; במקרה הגרוע הקובץ לא מצליח לנתח.

ל-JSON אין כלל כזה. ב-JSON, סדר המפתחות אפילו אינו משמעותי, ואובייקטים וסקלרים מתערבבים בחופשיות בתוך אותם סוגרים. אז המרה נאיבית של JSON ל-TOML שהולכת על האובייקט בסדר הכנסה ופולטת כל מפתח תוך כדי כך תייצר TOML שבור ברגע שבו סקלר עוקב אחר אובייקט מקונן.

הממיר פותר זאת על ידי ביצוע שני מעברים על כל טבלה תחילה הוא פולט את כל המפתחות הפשוטים, הסקלרים והמערכים המוטבעים רק אז הוא פולט את כותרות תת הטבלה ומערך הטבלאות, חוזר לתוך כל אחת סדר המפתחות שלך נשמר בתוך כל קבוצה, וזה מה שאתה רוצה, אבל הסידור מחדש הנדרש בין שתי הקבוצות קורה באופן אוטומטי אתה אף פעם לא צריך לחשוב על זה, ואתה אף פעם לא מקבל את השגיאה שקיבלתי.

מתי מערכים של אובייקטים צריכים להיות טבלאות לעומת מוטבעות?

הנה הבחירה האמיתית האחת ניתן לכתוב מערך של אובייקטים בשתי דרכים ב-TOML, ושניהם תקפים.

הראשון הוא an מערך טבלאות, צורת הסוגריים הכפולים. זה מילולי וקריא, בלוק אחד לכל רשומה, וכך נראה רוב ה-TOML בטבע. אם ראית א Cargo.toml עם כמה [[bin]] ערכים, ראית את זה.

[[servers]]
name = "web"
ip = "10.0.0.1"

[[servers]]
name = "api"
ip = "10.0.0.2"

השני הוא an טבלה מוטבעת בתוך מערך רגיל, אשר אורז כל אובייקט על קו אחד.

servers = [
  { name = "web", ip = "10.0.0.1" },
  { name = "api", ip = "10.0.0.2" },
]

שניהם הלוך ושוב לאותם נתונים איזה מהם אתה רוצה תלוי במטרה ובטעם מערכי טבלאות נקראים טוב יותר עבור רשומות שאדם יערוך, והם הקונבנציה עבור רוב תצורת הכלים טבלאות מוטבעות קומפקטיות יותר וקרובות יותר לצורת ה-JSON המקורי, שחלק מהאנשים מעדיפים כאשר הרשימה קצרה או שהאובייקטים זעירים הממיר כברירת מחדל למערכים של טבלאות ונותן לך מתג להחלפה אם אינך בטוח, השאר אותו על ברירת המחדל: כך נראה בדרך כלל קובץ TOML.

מה קורה ל-JSON null ב-TOML?

ל-TOML אין null. אין מילת מפתח, אין ערך ריק, כלום. זוהי החלטה עיצובית מכוונת של הפורמט, וזה המקום היחיד שבו JSON ל-TOML הוא באמת אובדן.

אז הממיר צריך לעשות בחירה, והוא מאפשר לך לעשות את זה כברירת מחדל, מפתח שהערך שלו הוא null נשמט, והכלי מפרט את המקשים שנפלו בפתק מתחת לפלט כך ששום דבר לא נעלם בשקט אם אתה מעדיף לשמור את המפתח, אתה יכול לעבור לכתיבת null כמחרוזת ריקה, אשר שומרת על המפתח במחיר של שינוי סוגו. nother אינו מושלם, כי אין תשובה מושלמת מה שחשוב הוא שהבחירה גלויה ולא קבורה.

אפס בתוך מערכים נשמטים תמיד, עם אזהרה, מכיוון שמערך TOML אינו יכול להכיל null כלל. אם ל-JSON שלך יש [1, null, 3], ה-TOML יהיה [1, 3] והכלי יגיד לך שהוא הסיר אחד. אם האפסים האלה נושאים משמעות, זה אות לעצב מחדש את הנתונים לפני ההמרה ולא אחריה.

מדוע המספר שלי איבד את העשרוני שלו, או זכה באחד?

זה מפתיע אנשים שאכפת להם מטיפוסים. JSON לא מבחין 5 מ 5.0. שניהם מנתחים לאותו IEEE 754 כפול, ועד אז JSON.parse נעשה אין זכר לאפס הנגרר אז כשהממיר רואה את המספר 5, אין לו דרך לדעת שהתכוונת לצוף, ומאז 5 האם מספר שלם הוא כותב מספר שלם של TOML.

TOML, לעומת זאת, אכן מבדיל בין מספרים שלמים למצופים, ולכמה כלים אכפת מההבדל. אם אתה צריך ערך שהוקלד כמצוף, התיקון הוא לתת לו חלק חלקי במקור, 5.1 או 5.0 כתוב בצורה ששורדת, או לערוך את הערך הבודד לאחר המרה זהו שינוי של תו אחד והוא נדיר, אבל כדאי לדעת למה זה קורה ולא להניח שהממיר טועה זה לא שגוי JSON פשוט זרק את המידע לפני שהממיר ראה אותו אי פעם.

המקרה ההפוך מופיע עם מספרים גדולים מאוד או קטנים מאוד, כאשר JavaScript's String() מייצר סימון מעריך כמו 1e+21. TOML מקבל את זה בתור צף, אז זה ממיר בסדר, אבל צורת המספר עשויה להיראות שונה ממה שהקלדת. שוב, הערך זהה; רק העיבוד השתנה.

כיצד פועלים מפתחות חשופים ומצוטטים?

TOML מאפשר לכתוב מפתח חשוף אם הוא עשוי רק מאותיות, ספרות, קווים תחתונים ומקפים. יש לצטט כל דבר אחר, מפתח עם נקודה, רווח, קו נטוי, תו Unicode. הממיר בודק כל מפתח ומצטט רק את אלה שזקוקים לו, אז user-name נשאר חשוף ו "user.name" מקבל ציטוטים כדי לעצור את קריאת הנקודה כנתיב טבלה. אתה לא צריך לחשוב על זה, אבל אם אתה רואה ציטוטים סביב מפתח בפלט, זו הסיבה: המפתח הכיל תו שאחרת ישנה את משמעותו.

דוגמה מעובדת

הנה המדגם שהכלי טוען, כך שתוכל לראות כל כלל בבת אחת. ה-JSON:

{
  "title": "Toolz config",
  "version": 2,
  "enabled": true,
  "owner": { "name": "Liton", "roles": ["admin", "editor"] },
  "database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
  "servers": [
    { "name": "web", "ip": "10.0.0.1" },
    { "name": "api", "ip": "10.0.0.2" }
  ]
}

הופך ל-TOML במקום שבו סקלרי השורש קודמים, האובייקטים המקוננים הופכים לטבלאות מנוקדות לפי הסדר, ומערך השרתים הופך לשניים [[servers]] בלוקים:

title = "Toolz config"
version = 2
enabled = true

[owner]
name = "Liton"
roles = ["admin", "editor"]

[database]
host = "localhost"
port = 5432

[database.pool]
min = 2
max = 10

[[servers]]
name = "web"
ip = "10.0.0.1"

[[servers]]
name = "api"
ip = "10.0.0.2"

שימו לב ש title, version ו enabled נכתבים לפני כל כותרת, roles נשאר מערך מוטבע כי הוא מערך של מחרוזות, ו [database.pool] יושב מתחת [database] כנתיב מנוקד כל כלל במדריך זה נראה בתשע שורות פלט.

איזה כלי לאיזו המרה?

TOML הוא פורמט אחד במשפחה, והכלי הנכון תלוי איפה אתה מתחיל ומסתיים הנה איך אני חושב על זה.

יש לך	אתה רוצה	להשתמש
JSON	TOML config	JSON ל-TOML
JSON	YAML config	JSON ל-YAML
ימל	JSON	YAML ל-JSON
JSON	XML	JSON ל-XML
Json מבולגן	קריא JSON	פורמט JSON

הדפוס הוא שפורמטים של תצורה הם תצוגות הניתנות להחלפה של אותם נתונים, והממיר הרצוי נקרא על שם הכיוון שאליו אתה הולך. TOML, YAML ו-JSON כולם מבטאים נתוני מפתח/ערך מקוננים; ההבדל הוא איזה מהם קורא כלי היעד שלך.

האם זה בטוח להמיר קובץ תצורה באינטרנט?

קבצי Config הם בדיוק מסוג הדברים שכדאי להיזהר מהדבקה באתר, מכיוון שלעתים קרובות הם מכילים מחרוזות חיבור, אסימונים וסודות אחרים ממיר JSON ל-TOML פועל כולו בדפדפן שלך ה-JSON שאתה מדביק מנותח בזיכרון במכשיר שלך, ה-TOML מיוצר שם, ושום דבר לא נשלח לשרת, נכתב ליומן או מאוחסן אתה יכול לצפות בזה בעצמך: פתח את לשונית הרשת שלך, הפעל המרה, וראה ששום בקשה לא יוצאת זה גם ממשיך לעבוד ללא חיבור לאחר טעינת הדף, וזו ההוכחה המעשית שהעבודה היא מקומית אם אכפת לך לאן הנתונים שלך הולכים, ועם קובץ תצורה כדאי לך, זה המאפיין שחשוב זה אותו עיקרון מאחורי כל כלי באתר, והסיבה שכתבתי על זה בהרחבה בהערה על פרטיות נתונים בכלים מקוונים.

איפה זה מתאים לזרימת עבודה אמיתית

המרת פורמט היא לעתים רחוקות כל המשימה זה צעד אתה שולף אובייקט הגדרות מתוך API, אתה ממיר אותו, אתה מפיל אותו לתוך פרויקט הערך של ממיר בצד הלקוח הוא שהוא חריצים לתוך כי זרימה ללא חיכוך: אין העלאה, אין חשבון, אין המתנה בשרת, אין תוהה אם הסודות שלך נמצאים עכשיו ב מישהו & #39;s יומנים. that is the same reason I keep the whole Toolz.dev הגדר את צד הלקוח, וזה נושא שאני חוזר אליו ב- כלי פרודוקטיביות למפתחים כתיבה, כי הכלים שאליהם מגיעים עשרים פעם ביום הם אלה שבהם מסתכמים נסיעה הלוך ושוב של שתי שניות ושאלת פרטיות.

TOML הרוויח את מקומו בזרימה הזו בכך שהוא משעמם בצורה הטובה ביותר. הוא מנתח את אותו הדבר בכל מקום, הוא קורא היטב, והקצה החד שלו, כלל הסדר, הוא בדיוק מסוג הדברים שממיר צריך להגיש עבורך. הדבק את ה-JSON שלך, בחר כיצד אתה רוצה לטפל במערכים וב-null, והעתק TOML שפשוט עובד.

שאלות נפוצות

כיצד אוכל להמיר JSON ל-TOML?

הדבק את אובייקט ה-JSON שלך בממיר ולחץ על המר הכלי מסדר אובייקטים לטבלאות TOML, מערכי אובייקטים למערכים של טבלאות וכל ערך אחר בשורה, ואז נותן לך TOML סטנדרטי להעתקה ה-JSON ברמה העליונה חייב להיות אובייקט, כי מסמך TOML הוא תמיד טבלה.

למה משמש TOML?

TOML הוא פורמט קובץ תצורה שנועד להיות קל לקריאה וחד משמעי לניתוח. זהו פורמט התצורה של Rust' s Cargo (Cargo.toml), אריזות Python (pyproject.toml), Hugo וכלי Go ו-Rust רבים. אנשים ממירים את JSON ל-TOML כדי להעביר תצורה שנוצרה על ידי מכונה לכלי שמצפה ל-TOML.

מה קורה לערכי Null של JSON ב-TOML?

ל-TOML אין סוג null, כך שלא ניתן לייצג Null JSON ישירות. כברירת מחדל, ממיר זה מפיל מקשי null ומוסיף הערה המפרטת אותם; אתה יכול לעבור לכתיבתם כמחרוזות ריקות במקום זאת. Nulls בתוך מערכים נשמטים תמיד, מכיוון שמערך TOML אינו יכול להכיל null.

מה ההבדל בין מערך טבלאות לטבלה מוטבעת?

מערך טבלאות משתמש בכותרות חוזרות ונשנות בסוגריים כפולים, בלוק אחד לכל רשומה, והוא הדרך האידיומטית של TOML לכתוב רשימה של אובייקטים כגון רשימת שרתים או תלות. טבלה מוטבעת אורזת אובייקט על שורה אחת כקבוצה של צמדי מפתח שווה ערך בסוגריים כלי זה כברירת מחדל למערכים של טבלאות אך מאפשר לך לבחור במקום זאת בשורה.

מדוע מספר ה-JSON שלי 5.0 הפך ל-5 ב-TOML?

JSON לא משמר את ההפרש בין 5 ל-5.0, כך שניתוח קורא את שניהם כמספר 5. מכיוון ש-5 הוא מספר שלם, הממיר כותב אותו כמספר שלם של TOML. אם אתה צריך את זה מוקלד כ-float, הוסף חלק חלקי במקור או ערוך את הערך הבודד לאחר ההמרה.

האם הממיר שומר על סדר המפתחות שלי?

כן. מפתחות נפלטים בסדר שהם מופיעים ב-JSON, עם סידור מחדש אחד נדרש: בתוך כל טבלה, מקשים רגילים נכתבים לפני כל כותרות של תת-טבלה או מערך טבלאות. זהו כלל תחביר TOML, לא בחירה של סדר מחדש, ובלעדיו הקובץ לא היה מנתח.

האם ה-JSON שלי מועלה לשרת?

מס 'המרה כולה מתרחשת בדפדפן שלך באמצעות JavaScript רגיל.JSON שלך, כולל כל סודות או אישורים בקובץ תצורה, לעולם לא משודר, נרשם או מאוחסן, והממיר ממשיך לעבוד ללא חיבור לאחר שהדף נטען.

למה כתוב שהרמה העליונה חייבת להיות אובייקט?

מסמך TOML מוגדר כטבלה, מה שאומר שהוא חייב להתחיל מקבוצה של צמדי מפתח/ערך למערך JSON חשוף או סקלרי אין טבלה למפות עליה. עטפו אותו תחילה באובייקט, למשל לשים את המערך שלכם מתחת למפתח בעל שם, והוא ימיר.