تامل 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 معتبری نباشد خطا پرتاب میکند؛ چون ریشه خطادار است، پروندهی خراب برنامه را با همان خطا تمام میکند. از آن به بعد تابعهای بستهی مقدار آن را میپیمایند.
واردسازی کدگذاری.تامل
واردسازی کدگذاری.مقدار
واردسازی مرتب سازی
تابع ریشه خطادار:
متن := `[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"))
پایان
پایانیک وابستگی ممکن است رشتهی سادهی نسخه باشد یا جدولی درونخطی با جزئیات بیشتر، پس برنامه پیش از خواندن با رشته است میپرسد. شیءها ترتیب کلیدهایشان را نگه نمیدارند؛ مرتب کردن کلیدهای شیء با مرتب سازی.مرتب سازی سریع فهرستی پایدار میدهد.
راهنما: تامل در یک ساختار
تنظیمهایی را که در همهجای برنامه به کار میبرید یک بار در یک ساختار بارگذاری کنید. مقدار کدگشاییشده را با جیسون.کدگذاری پیش فرض به جیسون تبدیل کنید و بگذارید جیسون.واسریال سازی آسان گیر ساختار را پر کند: کلیدهایی که پرونده ندارد پیشفرض ساختار را نگه میدارند و جدول [server] یک ساختار تودرتو را پر میکند.
واردسازی کدگذاری.تامل
واردسازی کدگذاری.جیسون
ساختار کارساز:
@جیسون "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
`
ناپایا ت := تنظیمات {}
تلاش:
سند := تامل.کدگشایی(متن)
جیسون.واسریال سازی آسان گیر(جیسون.کدگذاری پیش فرض(سند)، ت)
گرفتن خطا خ:
سرچاپ "تنظیمات خراب است:"، خ.به رشته()
برگشت ۱
پایان
سرچاپ ت.عنوان، "اشکالزدایی:"، ت.اشکال زدایی
سرچاپ "گوش دادن روی"، ت.کارساز اصلی.میزبان، ت.کارساز اصلی.درگاه
سرچاپ "شبکههای مجاز:"، ت.مجاز.طول()، ت.مجاز.بگیر(۰)
پایانراهنما: نوشتن پروندهی تامل
برای نوشتن تامل، یک شیء مقدار بسازید و به کدگذاری بدهید. شیء تودرتو یک [جدول] میشود. بالاترین سطح باید شیء باشد، چون سند تامل همیشه یک جدول است؛ کدگذاری برای هر چیز دیگری، و برای مقدار تهی درون آرایه، خطای پشتیبانی نشده پرتاب میکند و خ.مسیر میگوید کجاست.
واردسازی کدگذاری.تامل
واردسازی کدگذاری.مقدار
تابع نسخه پشتیبان(میزبان: رشته، وزن: صحیح): مقدار.مقدار:
ناپایا نسخه := مقدار.شیء جدید()
مقدار.تنظیم کلید(نسخه، "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"))
پایاندر خروجی سه چیز دیده میشود. password که تهی است نوشته نشده، چون TOML مقدار تهی ندارد. آرایهی شیءهای نسخهی پشتیبان در یک سطر و درونخطی نوشته شده است. عدد اعشاری 30.0 رقم .0 خود را نگه داشته، پس دوباره اعشاری خوانده میشود و نه عدد صحیح 30. کلیدها به ترتیب مشخصی نوشته نمیشوند، پس هرگز متن را با یک رشتهی ثابت مقایسه نکنید؛ داده را مقایسه کنید، مثلاً با مقدار.یکسان است پس از کدگشایی دوبارهی متن.
راهنما: گرفتن اشتباهها
کدگشایی سر نخستین اشتباه خطا پرتاب میکند و معتبر همان پرسش را با یک منطقی ساده پاسخ میدهد. خطا در خ.پیام میگوید چه چیزی نادرست است و در خ.خط و خ.ستون کجا؛ خ.نوع آن را دستهبندی میکند (نحو، اتمام ناگهانی، از قبل موجود، ناهمخوانی نوع، خارج از بازه، پشتیبانی نشده) و خ.کد دقیقاً نامش را میبرد، مثل toml.duplicate_key.
واردسازی کدگذاری.تامل
تابع بررسی(برچسب: رشته، متن: رشته):
تلاش:
تامل.کدگشایی(متن)
سرچاپ برچسب، "سالم"
گرفتن خطا خ:
سرچاپ برچسب، خ.پیام، "(خط " + خ.خط + "، ستون " + خ.ستون + ")"
پایان
پایان
تابع ریشه:
بررسی("درست: "، "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 = ")
پایاندو سطر آخر اشتباههایی هستند که تجزیهگری سهلگیرتر از آنها میگذشت: کلیدی که دو بار آمده، و mode = fast بدون نقلقولی که TOML دور رشته میخواهد. هر دو رد میشوند، پس پروندهای که کدگشایی شود دقیقاً همان چیزی را دارد که نوشته است.
تابعها
کدگشایی Decode
تابع کدگشایی(text: رشته): Throws<مقدار.مقدار>مقدار تبدیل میکند. اگر متن نادرست باشد، یک خطا با نوع، کدی به شکل toml.* و خط و ستون اشتباه پرتاب میکند.واردسازی کدگذاری.تامل
واردسازی کدگذاری.مقدار
تابع ریشه خطادار:
متن := "title = \"سلام\"\n\n[server]\nhost = \"localhost\"\nport = 8080\ntags = [\"a\", \"b\"]\n"
سرچاپ تامل.معتبر(متن)، تامل.معتبر("= بدون کلید")
م := تلاش تامل.کدگشایی(متن)
س := مقدار.مقدار کلید(م، "server")
سرچاپ مقدار.به رشته(مقدار.مقدار کلید(م، "title"))، مقدار.به صحیح(مقدار.مقدار کلید(س، "port"))
چاپ تلاش تامل.کدگذاری(م)
تلاش:
تامل.کدگشایی("a = 1\nb = \n")
گرفتن خطا خ:
سرچاپ خ.نام نوع()، خ.خط، خ.ستون، خ.کد
پایان
تلاش:
سرچاپ تامل.کدگذاری(مقدار.مقدار صحیح(۱))
گرفتن خطا خ:
سرچاپ خ.به رشته()
پایان
پایانمعتبر Valid
تابع معتبر(text: رشته): منطقینمونهی این مورد همراه با موارد بالاتر آمده است: encoding-toml-Decode.salam
کدگذاری Encode
تابع کدگذاری(v: مقدار.مقدار): Throws<رشته>پشتیبانی نشده پرتاب میکند.نمونهی این مورد همراه با موارد بالاتر آمده است: encoding-toml-Decode.salam