منسّق TOML

آخر تحديث: أبريل 2026

ما هو تنسيق TOML؟

TOML (Tom's Obvious Minimal Language) هي صيغة ملفات إعداد أنشأها Tom Preston-Werner عام 2013. تُربط مباشرةً بجدول hash وتستخدم تحديد الأنواع الصريح لجميع القيم. يأخذ منسّق TOML كودًا خامًا أو غير متسق الأسلوب ويُعيد تسلسله بمسافات موحّدة ومسافات بادئة صحيحة وترتيب مفاتيح قياسي. والنتيجة ملف يلتزم باصطلاحات موحّدة في جميع أنحاء مشروعك، مما يُسهّل مراجعة تغييرات الإعداد في الفروق.

حدّدت مواصفة TOML v1.0.0، التي اكتملت في يناير 2021، قواعد النحو بدقة كافية تجعل أي محلّل متوافق يُنتج بنية بيانات مطابقة من المدخل ذاته. لا يُغيّر التنسيق المحتوى الدلالي لملف 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. يُطبّق المنسّق تباعدًا وتجميعًا متسقًا على جميع هذه العناصر.

مقارنة TOML مع JSON وYAML

تحلّ TOML وJSON وYAML مشكلات متداخلة لكنها تتخذ خيارات مغايرة.

أمثلة برمجية

توضح الأمثلة أدناه كيفية تنسيق 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.toml

import 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.toml

package 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

الأسئلة الشائعة