آخرین بهروزرسانی: ۱۴۰۵ فروردین
فرمتبندی TOML چیست؟
TOML (زبان حداقلی آشکار تام) یک فرمت فایل پیکربندی است که تام پرستون-ورنر در سال ۲۰۱۳ طراحی کرد. این فرمت مستقیماً به یک جدول هش نگاشت میشود و از نوعگذاری صریح برای تمام مقادیر استفاده میکند. یک فرمتکننده TOML، فایلهای خام یا دارای سبک ناهماهنگ را میگیرد و با فاصلهگذاری یکنواخت، تورفتگی مناسب و ترتیب یکنواخت کلیدها، آنها را دوباره سریالسازی میکند. نتیجه فایلی است که در سراسر پروژه از قراردادهای یکسانی پیروی میکند و بررسی تغییرات پیکربندی در diffها را آسانتر میسازد.
مشخصات TOML v1.0.0 که در ژانویه ۲۰۲۱ نهایی شد، دستور زبان را به اندازهای دقیق تعریف میکند که هر تجزیهکننده مطابق با استاندارد از همان ورودی، ساختار داده یکسانی تولید کند. فرمتبندی محتوای معنایی فایل TOML را تغییر نمیدهد؛ تنها فضای خالی، گروهبندی کلیدها و سبک نقلقول را تنظیم میکند. این یعنی میتوانید فایلهای TOML را آزادانه فرمت کنید بدون نگرانی از خراب شدن رفتار برنامه.
برخلاف JSON، TOML از توضیحات، انواع بومی تاریخ-زمان و چندین فرم رشته (پایه، تحتاللفظی و چندخطی) پشتیبانی میکند. یک فرمتکننده خوب توضیحات را حفظ میکند و تمایز بین جداول درونخطی و سرصفحههای جدول استاندارد را رعایت میکند. همچنین آرایههای جداول را بهدرستی مدیریت میکند و گروهبندی بخشها را دستنخورده نگه میدارد تا فایل هم برای انسان و هم برای تجزیهکنندههای مصرفکننده خوانا بماند.
title = "My App" version = "1.0.0" debug = false [database] host = "localhost" port = 5432 name = "mydb" [database.pool] max_connections = 25 timeout = 30 [[servers]] name = "web" host = "web.example.com" [[servers]] name = "api" host = "api.example.com"
title="My App" version="1.0.0" debug=false [database] host="localhost" port=5432 name="mydb" [database.pool] max_connections=25 timeout=30 [[servers]] name="web" host="web.example.com" [[servers]] name="api" host="api.example.com"
چرا از فرمتکننده TOML استفاده کنیم؟
فایلهای پیکربندی با گذشت زمان و ویرایش توسط اعضای مختلف تیم، از نظر سبک دچار انحراف میشوند. تبها با فاصلهها مخلوط میشوند، برخی کلیدها بهصورت غیرضروری نقلقولگذاری میشوند و بخشهای جدول گروهبندی بصری خود را از دست میدهند. یک فرمتکننده TOML همه اینها را در یک پاس نرمالسازی میکند.
موارد استفاده از فرمتکننده TOML
مرجع نحو TOML
TOML مجموعه کوچکی از سازهها دارد. جدول زیر تمام عناصر ساختاری تعریفشده در مشخصات TOML v1.0.0 را فهرست میکند. یک فرمتکننده فاصلهگذاری و گروهبندی یکنواخت روی همه اینها اعمال میکند.
| نحو | نام | یادداشت |
|---|---|---|
| key = "value" | Basic key-value pair | Keys are bare or quoted; values are typed |
| [table] | Standard table | Creates a named section (hash table) |
| [a.b.c] | Dotted table | Shorthand for nested tables |
| [[array]] | Array of tables | Each [[name]] block appends to an array |
| key = """...\n""" | Multi-line basic string | Allows newlines, escapes processed |
| key = '''...\n''' | Multi-line literal string | Allows newlines, no escape processing |
| # comment | Comment | Extends to end of line; not in JSON output |
| {inline = true} | Inline table | Single-line table, no newlines allowed |
مقایسه TOML با JSON و YAML
TOML، JSON و YAML مشکلات مشابهی را حل میکنند اما مزایا و معایب متفاوتی دارند.
| ویژگی | TOML | JSON | YAML |
|---|---|---|---|
| توضیحات | # توضیحات خطی | پشتیبانی نمیشود | # توضیحات خطی |
| مقادیر نوعگذاریشده | رشته، عدد صحیح، اعشاری، بولی، تاریخ-زمان | رشته، عدد، بولی، null | ضمنی (مستعد خطا) |
| تودرتویی | سرصفحههای [جدول] | آکولاد | مبتنی بر تورفتگی |
| دقت مشخصات | دقیق (یک نتیجه تجزیه) | دقیق (RFC 8259) | شل (چندین تجزیه معتبر) |
| پشتیبانی از تاریخ/زمان | ۴ نوع بومی | ندارد (از رشته استفاده کنید) | ضمنی (شکننده) |
| کاما انتهایی | مجاز نیست | مجاز نیست | ندارد (بدون کاما) |
مثالهای کد
مثالهای زیر بهصورت برنامهنویسی TOML را در زبانها و ابزارهای مختلف فرمت میکنند. هر کدام یک فایل میخواند، آن را تجزیه میکند و نسخه فرمتشده را مینویسد.
import { parse, stringify } from '@iarna/toml'
import fs from 'fs'
const raw = fs.readFileSync('config.toml', 'utf-8')
const doc = parse(raw)
const formatted = stringify(doc)
// stringify() outputs canonical TOML with consistent spacing
fs.writeFileSync('config.toml', formatted)
// Quick one-liner with npx:
// npx taplo fmt config.tomlimport tomllib # Python 3.11+ (read-only)
import tomli_w # pip install tomli-w (write)
# Parse and re-serialize to format
with open("config.toml", "rb") as f:
data = tomllib.load(f)
formatted = tomli_w.dumps(data)
# tomli_w produces sorted keys, consistent quoting, and
# proper whitespace around = signs
print(formatted)
# CLI alternative: taplo fmt config.tomlpackage main
import (
"fmt"
"os"
"github.com/BurntSushi/toml"
"bytes"
)
func main() {
var data map[string]interface{}
_, err := toml.DecodeFile("config.toml", &data)
if err != nil {
fmt.Fprintln(os.Stderr, err) // parse error with line number
os.Exit(1)
}
var buf bytes.Buffer
enc := toml.NewEncoder(&buf)
enc.Indent = " "
enc.Encode(data) // re-serialized with consistent formatting
fmt.Print(buf.String())
}# Install taplo — the standard TOML toolkit cargo install taplo-cli # or: npm install -g @taplo/cli # Format a single file in place taplo fmt config.toml # Format all .toml files in a project taplo fmt # Check formatting without modifying (CI-friendly) taplo fmt --check # Validate TOML syntax without formatting taplo lint config.toml