کتابخانه‌ی استاندارد · کدگذاری و داده

تامل encoding.toml

خواندن و نوشتن پرونده‌های پیکربندی TOML.

واردسازی کدگذاری.تامل

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

TOML قالب پیکربندی‌ای است با جدول‌های [بخش] و سطرهای کلید = مقدار که در Cargo.toml، pyproject.toml و پیکربندی بسیاری از سرورها به کار می‌رود. این بسته متن TOML را به یک مقدار پویا تبدیل می‌کند و مقدار را دوباره به TOML می‌نویسد. سه تابع دارد: کدگشایی و معتبر برای خواندن، و کدگذاری برای نوشتن. کدگشایی و کدگذاری خطادار هستند: با ورودی خراب یک خطا پرتاب می‌کنند و هیچ نتیجه‌ی نیمه‌خوانده‌ای برنمی‌گردانند.

TOML برای پرونده‌هایی مناسب است که آدم‌ها با دست ویرایش می‌کنند. برای داده‌ای که برنامه‌ها با هم رد و بدل می‌کنند جیسون بهتر است، برای پرونده‌های YAML مثل پیکربندی CI یا کوبرنتیز یامل، و برای پرونده‌های رمز به شکل KEY=value بسته‌ی پرونده محیط. اگر فقط می‌خواهید تنظیم‌ها را با مقدار پیش‌فرض و جایگزینی از متغیرهای محیطی بخوانید، شاید بسته‌ی پیکربندی همین کار را انجام دهد.

هر بخش TOML به چه مقداری تبدیل می‌شود

TOMLمقدار
[table]، [a.b]، جدول درون‌خطی { k = v }، کلید نقطه‌دار a.b = 1شیء (تودرتو)
[[name]]آرایه‌ای از شیء‌ها
"basic" با نویسه‌های گریز، 'literal'رشته
42، -7، 1_000، 0x1F، 0o17، 0b101صحیح (۶۴ بیتی)
3.5، 1e6، inf، nanاعشاری
true، falseمنطقی
تاریخ و زمان، مثل 1979-05-27T07:32:00Zرشته، بدون تغییر

اشتباه‌های رایج

  • خطا کل خواندن را متوقف می‌کند. کدگشایی سر نخستین اشتباه خطا پرتاب می‌کند و خ.خط و خ.ستون جای آن را نشان می‌دهند، پس یک غلط تایپی هرگز بی‌صدا بقیه‌ی پرونده را حذف نمی‌کند. کلید یا [جدول]ی که دو بار تعریف شود، واژه‌ی بی‌نقل‌قولی مثل mode = fast، نویسه‌ی گریز نادرست و عدد صحیحی که در ۶۴ بیت جا نشود همه خطا هستند.
  • رشته‌ی چندخطی کار می‌کند. هر دو شکل """ و ''' خوانده می‌شوند، با حذف خط اول، ادامه‌ی خط با بک‌اسلش و نقل‌قول‌های درون متن. تاریخ‌ها رشته می‌مانند؛ اگر لازمشان دارید با بسته‌ی زمان تجزیه‌شان کنید.
  • نوشتن، قالب‌بندی نیست. کدگذاری کلیدها را به ترتیب ثابتی نمی‌نویسد، کلیدهای تهی را کنار می‌گذارد و آرایه‌ی شیء‌ها را به شکل آرایه‌ی درون‌خطی [{...}, {...}] می‌نویسد، نه بلوک‌های [[table]]. خروجی TOML درستی است و دوباره به همان داده خوانده می‌شود، ولی توضیح‌ها و چینش پرونده‌ی اصلی از دست می‌روند.

راهنما: خواندن مانیفست یک پروژه

پرونده‌های پروژه مثل Cargo.toml یا pyproject.toml جدول ساده، جدول درون‌خطی و آرایه‌ی جدول را با هم دارند. کدگشایی کل پرونده را در یک مقدار می‌خواند، یا اگر TOML معتبری نباشد خطا پرتاب می‌کند؛ چون ریشه خطادار است، پرونده‌ی خراب برنامه را با همان خطا تمام می‌کند. از آن به بعد تابع‌های بسته‌ی مقدار آن را می‌پیمایند.

encoding-toml-guide-manifest.salam
واردسازی کدگذاری.تامل
واردسازی کدگذاری.مقدار
واردسازی مرتب سازی

تابع ریشه خطادار:
    متن := `[package]
name = "shop"
version = "1.4.0"
authors = ["Sara", "Reza"]

[dependencies]
http = "2.1"
json = { version = "1.0", optional = true }
log = "0.9"

[[bin]]
name = "shop"
path = "src/main.salam"

[[bin]]
name = "shop-admin"
path = "src/admin.salam"
`
    سند := تلاش تامل.کدگشایی(متن)
    مشخصات := مقدار.مقدار کلید(سند، "package")
    سرچاپ مقدار.به رشته(مقدار.مقدار کلید(مشخصات، "name"))، مقدار.به رشته(مقدار.مقدار کلید(مشخصات، "version"))
    سرچاپ "نویسندگان:"، مقدار.طول آرایه(مقدار.مقدار کلید(مشخصات، "authors"))

    وابستگی‌ها := مقدار.مقدار کلید(سند، "dependencies")
    نام‌ها := مقدار.کلیدهای شیء(وابستگی‌ها)
    مرتب سازی.مرتب سازی سریع(نام‌ها)
    هر نام در نام‌ها:
        وابستگی := مقدار.مقدار کلید(وابستگی‌ها، نام)
        اگر مقدار.رشته است(وابستگی):
            سرچاپ "وابستگی"، نام، مقدار.به رشته(وابستگی)
        وگرنه:
            سرچاپ "وابستگی"، نام، مقدار.به رشته(مقدار.مقدار کلید(وابستگی، "version"))، "(اختیاری)"
        پایان
    پایان

    برنامه‌ها := مقدار.مقدار کلید(سند، "bin")
    تکرار مقدار.طول آرایه(برنامه‌ها) در ای:
        ب := مقدار.عضو آرایه(برنامه‌ها، ای)
        سرچاپ "برنامه"، مقدار.به رشته(مقدار.مقدار کلید(ب، "name"))، "از"، مقدار.به رشته(مقدار.مقدار کلید(ب، "path"))
    پایان
پایان
خروجیshop 1.4.0 نویسندگان: 2 وابستگی http 2.1 وابستگی json 1.0 (اختیاری) وابستگی log 0.9 برنامه shop از src/main.salam برنامه shop-admin از src/admin.salam

یک وابستگی ممکن است رشته‌ی ساده‌ی نسخه باشد یا جدولی درون‌خطی با جزئیات بیشتر، پس برنامه پیش از خواندن با رشته است می‌پرسد. شیء‌ها ترتیب کلیدهایشان را نگه نمی‌دارند؛ مرتب کردن کلیدهای شیء با مرتب سازی.مرتب سازی سریع فهرستی پایدار می‌دهد.

راهنما: تامل در یک ساختار

تنظیم‌هایی را که در همه‌جای برنامه به کار می‌برید یک بار در یک ساختار بارگذاری کنید. مقدار کدگشایی‌شده را با جیسون.کدگذاری پیش فرض به جیسون تبدیل کنید و بگذارید جیسون.واسریال سازی آسان گیر ساختار را پر کند: کلیدهایی که پرونده ندارد پیش‌فرض ساختار را نگه می‌دارند و جدول [server] یک ساختار تودرتو را پر می‌کند.

encoding-toml-guide-struct.salam
واردسازی کدگذاری.تامل
واردسازی کدگذاری.جیسون

ساختار کارساز:
    @جیسون "host"
    همگانی میزبان: رشته = "127.0.0.1"
    @جیسون "port"
    همگانی درگاه: صحیح = ۸۰۰۰
پایان

ساختار تنظیمات:
    @جیسون "title"
    همگانی عنوان: رشته = ""
    @جیسون "debug"
    همگانی اشکال زدایی: منطقی = نادرست
    @جیسون "server"
    همگانی کارساز اصلی: کارساز = کارساز {}
    @جیسون "allowed"
    همگانی مجاز: وکتور<رشته> = وکتور {}
پایان

تابع ریشه:
    متن := `title = "Shop admin"
allowed = ["10.0.0.0/8", "192.168.1.0/24"]

[server]
port = 9090
`
    ناپایا ت := تنظیمات {}
    تلاش:
        سند := تامل.کدگشایی(متن)
        جیسون.واسریال سازی آسان گیر(جیسون.کدگذاری پیش فرض(سند)، ت)
    گرفتن خطا خ:
        سرچاپ "تنظیمات خراب است:"، خ.به رشته()
        برگشت ۱
    پایان
    سرچاپ ت.عنوان، "اشکال‌زدایی:"، ت.اشکال زدایی
    سرچاپ "گوش دادن روی"، ت.کارساز اصلی.میزبان، ت.کارساز اصلی.درگاه
    سرچاپ "شبکه‌های مجاز:"، ت.مجاز.طول()، ت.مجاز.بگیر(۰)
پایان
خروجیShop admin اشکال‌زدایی: false گوش دادن روی 127.0.0.1 9090 شبکه‌های مجاز: 2 10.0.0.0/8

راهنما: نوشتن پرونده‌ی تامل

برای نوشتن تامل، یک شیء مقدار بسازید و به کدگذاری بدهید. شیء تودرتو یک [جدول] می‌شود. بالاترین سطح باید شیء باشد، چون سند تامل همیشه یک جدول است؛ کدگذاری برای هر چیز دیگری، و برای مقدار تهی درون آرایه، خطای پشتیبانی نشده پرتاب می‌کند و خ.مسیر می‌گوید کجاست.

encoding-toml-guide-write.salam
واردسازی کدگذاری.تامل
واردسازی کدگذاری.مقدار

تابع نسخه پشتیبان(میزبان: رشته، وزن: صحیح): مقدار.مقدار:
    ناپایا نسخه := مقدار.شیء جدید()
    مقدار.تنظیم کلید(نسخه، "host"، مقدار.مقدار رشته(میزبان))
    مقدار.تنظیم کلید(نسخه، "weight"، مقدار.مقدار صحیح(وزن))
    برگشت نسخه
پایان

تابع ریشه خطادار:
    ناپایا پایگاه := مقدار.شیء جدید()
    مقدار.تنظیم کلید(پایگاه، "url"، مقدار.مقدار رشته("postgres://localhost/shop"))
    مقدار.تنظیم کلید(پایگاه، "pool"، مقدار.مقدار صحیح(۸))
    مقدار.تنظیم کلید(پایگاه، "timeout"، مقدار.مقدار اعشاری(۳۰.۰))
    مقدار.تنظیم کلید(پایگاه، "password"، مقدار.مقدار تهی())

    ناپایا نسخه‌ها := مقدار.آرایه جدید()
    مقدار.افزودن به آرایه(نسخه‌ها، نسخه پشتیبان("10.0.0.2"، ۲))
    مقدار.افزودن به آرایه(نسخه‌ها، نسخه پشتیبان("10.0.0.3"، ۱))
    مقدار.تنظیم کلید(پایگاه، "replicas"، نسخه‌ها)

    ناپایا ریشه داده := مقدار.شیء جدید()
    مقدار.تنظیم کلید(ریشه داده، "database"، پایگاه)

    متن := تلاش تامل.کدگذاری(ریشه داده)
    چاپ متن

    برگشتی := مقدار.مقدار کلید(تلاش تامل.کدگشایی(متن)، "database")
    سرچاپ "timeout هنوز اعشاری است:"، مقدار.اعشاری است(مقدار.مقدار کلید(برگشتی، "timeout"))
    سرچاپ "password نوشته شد:"، مقدار.شیء دارد(برگشتی، "password")
    سرچاپ "نسخه‌های پشتیبان خوانده‌شده:"، مقدار.طول آرایه(مقدار.مقدار کلید(برگشتی، "replicas"))
پایان
خروجی[database] url = "postgres://localhost/shop" pool = 8 timeout = 30.0 replicas = [{host = "10.0.0.2", weight = 2}, {host = "10.0.0.3", weight = 1}] timeout هنوز اعشاری است: true password نوشته شد: false نسخه‌های پشتیبان خوانده‌شده: 2

در خروجی سه چیز دیده می‌شود. password که تهی است نوشته نشده، چون TOML مقدار تهی ندارد. آرایه‌ی شیء‌های نسخه‌ی پشتیبان در یک سطر و درون‌خطی نوشته شده است. عدد اعشاری 30.0 رقم .0 خود را نگه داشته، پس دوباره اعشاری خوانده می‌شود و نه عدد صحیح 30. کلیدها به ترتیب مشخصی نوشته نمی‌شوند، پس هرگز متن را با یک رشته‌ی ثابت مقایسه نکنید؛ داده را مقایسه کنید، مثلاً با مقدار.یکسان است پس از کدگشایی دوباره‌ی متن.

راهنما: گرفتن اشتباه‌ها

کدگشایی سر نخستین اشتباه خطا پرتاب می‌کند و معتبر همان پرسش را با یک منطقی ساده پاسخ می‌دهد. خطا در خ.پیام می‌گوید چه چیزی نادرست است و در خ.خط و خ.ستون کجا؛ خ.نوع آن را دسته‌بندی می‌کند (نحو، اتمام ناگهانی، از قبل موجود، ناهمخوانی نوع، خارج از بازه، پشتیبانی نشده) و خ.کد دقیقاً نامش را می‌برد، مثل toml.duplicate_key.

encoding-toml-guide-errors.salam
واردسازی کدگذاری.تامل

تابع بررسی(برچسب: رشته، متن: رشته):
    تلاش:
        تامل.کدگشایی(متن)
        سرچاپ برچسب، "سالم"
    گرفتن خطا خ:
        سرچاپ برچسب، خ.پیام، "(خط " + خ.خط + "، ستون " + خ.ستون + ")"
    پایان
پایان

تابع ریشه:
    بررسی("درست:              "، "a = 1\nb = 'two'\n")
    بررسی("بی مقدار:          "، "a = \n")
    بررسی("رشته‌ی بسته‌نشده:  "، "a = \"open\n")
    بررسی("آرایه‌ی بسته‌نشده: "، "a = [1, 2\n")
    بررسی("جدول بسته‌نشده:    "، "[server\nport = 1\n")
    بررسی("متن چندخطی:        "، "a = \"\"\"x\"\"\"\n")
    بررسی("کلید تکراری:       "، "a = 1\na = 2\n")
    بررسی("رشته‌ی بی‌نقل‌قول:  "، "mode = fast\n")
    سرچاپ "معتبر هم همین را می‌گوید:"، تامل.معتبر("a = 1")، تامل.معتبر("a = ")
پایان
خروجیدرست: سالم بی مقدار: expected a value (خط 1، ستون 5) رشته‌ی بسته‌نشده: the string is not closed before the end of the line (خط 1، ستون 5) آرایه‌ی بسته‌نشده: the array is not closed (خط 1، ستون 5) جدول بسته‌نشده: expected ']' to close the table header (خط 1، ستون 8) متن چندخطی: multi-line strings (""") are not supported (خط 1، ستون 5) کلید تکراری: duplicate key 'a' (خط 2، ستون 1) رشته‌ی بی‌نقل‌قول: invalid value 'fast' (خط 1، ستون 8) معتبر هم همین را می‌گوید: true false

دو سطر آخر اشتباه‌هایی هستند که تجزیه‌گری سهل‌گیرتر از آن‌ها می‌گذشت: کلیدی که دو بار آمده، و mode = fast بدون نقل‌قولی که TOML دور رشته می‌خواهد. هر دو رد می‌شوند، پس پرونده‌ای که کدگشایی شود دقیقاً همان چیزی را دارد که نوشته است.

تابع‌ها

کدگشایی Decode

تابع کدگشایی(text: رشته): Throws<مقدار.مقدار>
TOML را به یک مقدار تبدیل می‌کند. اگر متن نادرست باشد، یک خطا با نوع، کدی به شکل toml.* و خط و ستون اشتباه پرتاب می‌کند.
encoding-toml-Decode.salam
واردسازی کدگذاری.تامل
واردسازی کدگذاری.مقدار

تابع ریشه خطادار:
    متن := "title = \"سلام\"\n\n[server]\nhost = \"localhost\"\nport = 8080\ntags = [\"a\", \"b\"]\n"
    سرچاپ تامل.معتبر(متن)، تامل.معتبر("= بدون کلید")
    م := تلاش تامل.کدگشایی(متن)
    س := مقدار.مقدار کلید(م، "server")
    سرچاپ مقدار.به رشته(مقدار.مقدار کلید(م، "title"))، مقدار.به صحیح(مقدار.مقدار کلید(س، "port"))
    چاپ تلاش تامل.کدگذاری(م)
    تلاش:
        تامل.کدگشایی("a = 1\nb = \n")
    گرفتن خطا خ:
        سرچاپ خ.نام نوع()، خ.خط، خ.ستون، خ.کد
    پایان
    تلاش:
        سرچاپ تامل.کدگذاری(مقدار.مقدار صحیح(۱))
    گرفتن خطا خ:
        سرچاپ خ.به رشته()
    پایان
پایان
خروجیtrue false سلام 8080 title = "سلام" [server] host = "localhost" port = 8080 tags = ["a", "b"] syntax error 2 5 toml.expected_value toml: the top level must be an object, since a TOML document is a table, not an integer

معتبر Valid

تابع معتبر(text: رشته): منطقی
اگر متن TOML درستی باشد، درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: encoding-toml-Decode.salam

کدگذاری Encode

تابع کدگذاری(v: مقدار.مقدار): Throws<رشته>
مقدار را به TOML تبدیل می‌کند؛ کلیدهای تهی در جدول کنار گذاشته می‌شوند. اگر سطح بالا شیء نباشد یا آرایه‌ای مقدار تهی داشته باشد، خطای پشتیبانی نشده پرتاب می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: encoding-toml-Decode.salam