مبدل JSON <> TOML

مبدل JSON ↔ TOML چگونه کار می‌کند

این ابزار چه کاری انجام می‌دهد

مبدل JSON ↔ TOML داده را بین قالب‌های JSON و TOML (Tom's Obvious, Minimal Language) تبدیل می‌کند و ساختار و مقادیر داده را حفظ می‌کند. این مبدل تبدیل دوطرفه را انجام می‌دهد: json به toml و toml به json. TOML معمولاً برای فایل‌های پیکربندی در پروژه‌هایی مانند Cargo در Rust، Poetry در Python و بسیاری ابزارهای دیگر استفاده می‌شود. این مبدل از تورفتگی قابل‌تنظیم برای خروجی JSON پشتیبانی می‌کند و به شما اجازه می‌دهد بین تورفتگی ۲ فاصله‌ای یا ۴ فاصله‌ای انتخاب کنید تا با راهنمای سبک پروژه‌تان هماهنگ باشد.

موارد استفادهٔ رایج برای توسعه‌دهندگان

توسعه‌دهندگان از مبدل‌های JSON TOML هنگام کار با فایل‌های پیکربندی استفاده می‌کنند، به‌ویژه در پروژه‌های Rust (Cargo.toml)، پروژه‌های Python (pyproject.toml)، یا هنگام مهاجرت بین قالب‌های پیکربندی. بسیاری از ابزارهای مدرن از TOML برای پیکربندی استفاده می‌کنند چون از JSON خواناتر است و در عین حال توسط ماشین قابل‌پردازش است. این مبدل هنگام مهاجرت پیکربندی بین قالب‌ها، استانداردسازی پیکربندی بین ابزارها، یا کار با سیستم‌هایی که به قالب مشخصی نیاز دارند ارزشمند است. پیش از تبدیل، ممکن است بخواهید JSON خود را با JSON Formatter قالب‌بندی کنید یا TOML را با TOML Formatter قالب‌بندی کنید تا خوانایی بهتر شود. این مبدل هنگام دیباگ مشکلات پیکربندی، مقایسهٔ قالب‌ها، یا آماده‌سازی داده برای ابزارهای مختلفی که JSON یا TOML انتظار دارند کمک می‌کند.

قالب‌ها، نوع‌ها یا گونه‌های داده

JSON و TOML هر دو قالب‌های سریال‌سازی داده هستند، اما نحو و قابلیت‌های متفاوتی دارند. JSON از object، array، string، number، boolean و null پشتیبانی می‌کند. TOML از همان نوع‌های داده پشتیبانی می‌کند به‌علاوهٔ قابلیت‌های اضافی مانند کامنت‌ها، جدول‌های درون‌خطی (inline tables) و آرایه‌ای از جدول‌ها (array of tables). این مبدل نحو استاندارد JSON و نحو رایج TOML (TOML v1.0.0) را مدیریت می‌کند. هنگام تبدیل، قابلیت‌های مخصوص TOML مانند کامنت‌ها هنگام تبدیل به JSON از بین می‌روند، چون JSON از کامنت پشتیبانی نمی‌کند. جدول‌های درون‌خطی TOML و آرایهٔ جدول‌ها به‌ترتیب به objectها و arrayهای JSON تبدیل می‌شوند. مبدل نوع‌های داده را حفظ می‌کند، اما برخی موارد لبه‌ای وجود دارد: نوع‌های تاریخ-زمان TOML به رشته‌های JSON تبدیل می‌شوند و ساختار جدول‌های TOML به objectهای تو‌در‌تو در JSON تخت‌سازی می‌شود.

دام‌های رایج و حالت‌های لبه‌ای

یکی از مشکلات رایج این است که کامنت‌های TOML هنگام تبدیل به JSON از بین می‌روند، چون JSON از کامنت پشتیبانی نمی‌کند. دام دیگر، مدیریت جدول‌های TOML است: TOML از سرآیندهای جدول مانند [table] استفاده می‌کند که به objectهای تو‌در‌تو در JSON تبدیل می‌شوند. آرایهٔ جدول‌ها در TOML (با [[array]]) به آرایه‌های JSON تبدیل می‌شود. مقادیر تاریخ و تاریخ‌زمان در TOML به رشته‌های JSON در قالب ISO 8601 تبدیل می‌شوند. هنگام تبدیل ساختارهای بزرگ و تو‌در‌تو، مطمئن شوید خروجی با انتظار شما مطابقت دارد، به‌ویژه برای موارد لبه‌ای مانند آرایه‌های خالی، مقادیر null و اشیای عمیقاً تو‌در‌تو. جدول‌های درون‌خطی TOML (با { key = value }) به objectهای JSON تبدیل می‌شوند.

چه زمانی از این ابزار استفاده کنیم در برابر کُد

از این مبدل برای تبدیل سریع قالب‌ها، تبدیل‌های یک‌باره، یا زمانی که خارج از محیط توسعه کار می‌کنید استفاده کنید. برای تبدیل فایل‌های پیکربندی، مقایسهٔ قالب‌ها، یا آماده‌سازی داده برای ابزارهای مختلف ایده‌آل است. برای کدِ تولیدی (production)، از کتابخانه‌های تبدیل که در برنامهٔ شما یکپارچه شده‌اند استفاده کنید تا تبدیل قالب‌ها را به‌عنوان بخشی از پایپ‌لاین‌های پردازش داده انجام دهند. کتابخانه‌های پارس TOML و JSON خطایابی بهتر، ایمنی نوع و یکپارچگی با کدبیس شما را فراهم می‌کنند. ابزارهای مرورگر در تبدیل‌های موردی (ad-hoc) و اکتشاف عالی هستند، در حالی که راهکارهای مبتنی بر کد اتوماسیون، اعتبارسنجی و یکپارچگی با پایپ‌لاین‌های CI/CD را ارائه می‌دهند.