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

یامل `encoding/yaml`

خواندن یامل با مسیر، ساختن و نوشتن آن، و تبدیل به جیسون.

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

در این صفحه

راهنما: خواندن پیکربندی با مقدارهای پیش‌فرض
راهنما: یامل در یک ساختار
راهنما: پیمودن فهرستی از رکوردها
راهنما: چند سند در یک پرونده
راهنما: مقدار چه گونه‌ای گرفت؟
کدام تابع برای کدام کار
تابع‌ها

یامل قالب رایج پرونده‌های پیکربندی است. این بسته یامل را درونی به جیسون تبدیل می‌کند؛ برای همین، هم تابع‌های خواندنش ساده‌اند و هم با بسته‌ی جیسون جور می‌شود.

تابع‌های خواندن یک مسیر می‌گیرند: کلیدها با نقطه از هم جدا می‌شوند و شماره‌ی عضو فهرست داخل کروشه می‌آید، مثل app.hosts[1]. اگر مسیر پیدا نشود، رشته‌ی خالی یا صفر برمی‌گردد؛ برای تشخیص نبودن، دارد را به کار ببرید.

این بسته یاملی را که پرونده‌های پیکربندی به کار می‌برند می‌خواند: نگاشت‌های تودرتو، فهرست به شکل خط‌تیره‌ای و [flow]، رشته‌های داخل نقل‌قول، متن چندخطی با | و >، توضیح‌ها و چند سند در یک پرونده. برای تنظیمات ساده‌ی key = value با بخش‌ها و لایه‌ها، پیکربندی ساده‌تر است و یامل را هم می‌خواند.

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

لنگرها و ارجاع‌ها (&base، *base، <<: *base) پشتیبانی نمی‌شوند. مقداری مثل &a 1 رشته‌ی &a 1 خوانده می‌شود، و لنگر روی یک نگاشت، مثل base: &base با کلیدهای تورفته پس از آن، بقیه‌ی سند را بی‌هیچ خطایی از دست می‌دهد. چنین پرونده‌هایی را کامل بنویسید یا پیش از خواندن با ابزار دیگری بازشان کنید.
yes، no، on و off رشته‌اند، مثل یامل ۱٫۲، پس دریافت منطقی برایشان نادرست است. فقط true و false منطقی‌اند.
دریافت عدد یک صحیح ۳۲ بیتی برمی‌گرداند و برای عددهای بزرگ‌تر سرریز می‌کند. اندازه‌ها، شناسه‌ها و برچسب‌های زمانی را از راه به جیسون در یک فیلد صحیح۶۴ بخوانید (پایین‌تر را ببینید).
هر تابع مسیر کل متن را دوباره تجزیه می‌کند. برای خواندن‌های زیاد از یک پرونده‌ی بزرگ، یک بار به جیسون یا کدگشایی را صدا بزنید و روی نتیجه کار کنید.

راهنما: خواندن پیکربندی با مقدارهای پیش‌فرض

تابع‌های مسیری سریع‌ترین راه خواندن پرونده‌ی پیکربندی‌اند. اول با دارد کلیدها مطمئن شوید بخش‌هایی که به آن‌ها تکیه دارید هستند، سپس هر تنظیم را با تابع گونه‌دار خودش بخوانید. برای تنظیم‌های اختیاری، دریافت را در یک تابع کمکی کوچک بپیچید که وقتی دارد می‌گوید کلید نیست، مقدار پیش‌فرض را برگرداند.

encoding-yaml-guide-config.salam

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

تابع تنظیم(متن: رشته، مسیر: رشته، پیش فرض: رشته): رشته:
    اگر یامل.دارد(متن، مسیر):
        برگشت یامل.دریافت(متن، مسیر)
    پایان
    برگشت پیش فرض
پایان

تابع ریشه:
    متن := `# settings for the shop
server:
  host: 0.0.0.0
  port: 8080
  workers: 4
log:
  level: debug
features:
  search: true
  beta: false
`
    ناپایا لازم := وکتور {} برگردان وکتور<رشته>
    لازم.بیفزا("server")
    لازم.بیفزا("log")
    اگر وارونه یامل.دارد کلیدها(متن، لازم):
        سرچاپ "یکی از بخش‌های پیکربندی نیست"
        برگشت ۱
    پایان

    سرچاپ "گوش دادن روی"، یامل.دریافت(متن، "server.host") + ":" + یامل.دریافت(متن، "server.port")
    سرچاپ "کارگرها:"، یامل.دریافت عدد(متن، "server.workers")
    سرچاپ "سطح گزارش:"، تنظیم(متن، "log.level"، "info")
    سرچاپ "پرونده‌ی گزارش:"، تنظیم(متن، "log.file"، "stdout")
    سرچاپ "جستجو روشن:"، یامل.دریافت منطقی(متن، "features.search")، "آزمایشی روشن:"، یامل.دریافت منطقی(متن، "features.beta")
    سرچاپ "پرچم‌های ویژگی:"، یامل.کلیدها(متن، "features")
پایان

خروجیگوش دادن روی 0.0.0.0:8080 کارگرها: 4 سطح گزارش: debug پرونده‌ی گزارش: stdout جستجو روشن: true آزمایشی روشن: false پرچم‌های ویژگی: ["search", "beta"]

توضیح‌هایی که با # شروع می‌شوند نادیده گرفته می‌شوند. دریافت عدد و دریافت منطقی برای کلید نبوده ۰ و نادرست برمی‌گردانند که خودشان مقدار واقعی هم هستند، پس پیش‌فرضی غیر از صفر به بررسی دارد نیاز دارد.

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

برای پیکربندی‌ای با فیلدهای زیاد، یک ساختار از یک متن و فهرستی از مسیرها راحت‌تر جابه‌جا می‌شود. یامل واسریال‌سازی جداگانه‌ای ندارد و لازم هم نیست: به جیسون یامل را به جیسون تبدیل می‌کند و بسته‌ی جیسون ساختار را پر می‌کند، با همان نام‌های @جیسون و همان پیش‌فرض‌ها.

encoding-yaml-guide-struct.salam

واردسازی کدگذاری.یامل
واردسازی کدگذاری.جیسون
واردسازی کدگذاری.خطای کدگذاری

ساختار سرویس:
    @جیسون "name"
    همگانی نام: رشته = ""
    @جیسون "image"
    همگانی تصویر: رشته = ""
    @جیسون "replicas"
    همگانی نسخه‌ها: صحیح = ۱
    @جیسون "ports"
    همگانی درگاه‌ها: وکتور<صحیح> = وکتور {}
پایان

تابع ریشه:
    متن := `name: api
image: shop/api:2.3
ports:
  - 80
  - 443
`
    ناپایا س := سرویس {}
    ناپایا خطا := خطای کدگذاری.بدون خطا()
    اگر وارونه جیسون.واسریال سازی آسان گیر(یامل.به جیسون(متن)، س، خطا):
        سرچاپ "سرویس خراب است:"، خطا.پیام
        برگشت ۱
    پایان
    سرچاپ س.نام، "این تصویر را اجرا می‌کند:"، س.تصویر
    سرچاپ "نسخه‌ها:"، س.نسخه‌ها
    سرچاپ "درگاه‌ها:"، س.درگاه‌ها.طول()، س.درگاه‌ها.بگیر(۰)، س.درگاه‌ها.بگیر(۱)
پایان

خروجیapi این تصویر را اجرا می‌کند: shop/api:2.3 نسخه‌ها: 1 درگاه‌ها: 2 80 443

replicas در پرونده نیست، پس پیش‌فرض ۱ می‌ماند، چون نسخه‌ی آسان‌گیر به کار رفته است. با جیسون.واسریال سازی نبودن این کلید خطا می‌شد.

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

فهرستی از شیء‌ها، مثل کارهای یک پرونده‌ی CI، با طول و یک شماره در مسیر خوانده می‌شود. مسیر عضو ای را یک بار بسازید و نام فیلدها را به آن بیفزایید. [lint] شکل کوتاه و یک‌خطی فهرست است و مثل شکل خط‌تیره‌دار خوانده می‌شود.

encoding-yaml-guide-list.salam

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

تابع ریشه:
    متن := `jobs:
  - name: lint
    run: salam format --check
  - name: test
    run: sh tests/run.sh
    needs: [lint]
  - name: deploy
    run: sh deploy.sh
    needs: [test]
    branch: main
`
    تعداد := یامل.طول(متن، "jobs")
    سرچاپ تعداد، "کار"
    تکرار تعداد در ای:
        جا := "jobs[" + رشته.از عدد(ای) + "]"
        سطر := یامل.دریافت(متن، جا + ".name") + ": " + یامل.دریافت(متن، جا + ".run")
        اگر یامل.دارد(متن، جا + ".needs"):
            سرچاپ سطر، "(پس از"، یامل.دریافت(متن، جا + ".needs[0]") + ")"
        وگرنه:
            سرچاپ سطر
        پایان
        اگر یامل.دارد(متن، جا + ".branch"):
            سرچاپ "  فقط روی"، یامل.دریافت(متن، جا + ".branch")
        پایان
    پایان
پایان

خروجی3 کار lint: salam format --check test: sh tests/run.sh (پس از lint) deploy: sh deploy.sh (پس از test) فقط روی main

راهنما: چند سند در یک پرونده

مانیفست‌های کوبرنتیز و برخی قالب‌های گزارش چند سند یامل را در یک پرونده می‌گذارند که با سطری از --- جدا شده‌اند. تفکیک کردن اسناد آن‌ها را از هم جدا می‌کند و هر تکه سپس یک متن یامل معمولی برای تابع‌های دیگر است.

encoding-yaml-guide-multi.salam

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

تابع ریشه:
    متن := `kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
---
kind: Service
metadata:
  name: web
spec:
  port: 80
---
kind: ConfigMap
metadata:
  name: web-config
`
    اسناد := یامل.تفکیک کردن اسناد(متن)
    سرچاپ اسناد.طول()، "سند"
    هر سند در اسناد:
        سرچاپ "-"، یامل.دریافت(سند، "kind")، یامل.دریافت(سند، "metadata.name")، "معتبر:"، یامل.معتبر(سند)
    پایان
    سرچاپ "Deployment به شکل جیسون:"، یامل.به جیسون(اسناد.بگیر(۰))
پایان

خروجی3 سند - Deployment web معتبر: true - Service web معتبر: true - ConfigMap web-config معتبر: true Deployment به شکل جیسون: {"kind": "Deployment", "metadata": {"name": "web"}, "spec": {"replicas": 3}}

به جیسون راه سپردن یامل به هر چیزی است که جیسون می‌فهمد، مثل یک API از راه HTTP. در جهت دیگر، برونریزی متن جیسون را به شکل یامل می‌نویسد.

راهنما: مقدار چه گونه‌ای گرفت؟

یامل گونه‌ی هر مقدار را از ظاهرش تعیین می‌کند و نتیجه همیشه همانی نیست که نویسنده می‌خواست. نوع نشان می‌دهد خواننده چه دیده است. این‌جا yes رشته مانده، 007 صفرهایش را به شکل رشته نگه داشته، و سقف پنج گیگابایتی برای دریافت عدد بزرگ است ولی برای فیلد صحیح۶۴ مشکلی ندارد.

encoding-yaml-guide-types.salam

واردسازی کدگذاری.یامل
واردسازی کدگذاری.جیسون
واردسازی کدگذاری.خطای کدگذاری

ساختار محدودیت‌ها:
    @جیسون "max_upload"
    همگانی بیشترین بارگذاری: صحیح۶۴ = ۰
    @جیسون "public"
    همگانی عمومی: منطقی = نادرست
    @جیسون "code"
    همگانی کد: رشته = ""
پایان

تابع بارگذاری(متن: رشته):
    ناپایا م := محدودیت‌ها {}
    ناپایا خطا := خطای کدگذاری.بدون خطا()
    اگر جیسون.واسریال سازی آسان گیر(یامل.به جیسون(متن)، م، خطا):
        سرچاپ "  بارگذاری شد:"، م.بیشترین بارگذاری، م.عمومی، م.کد
    وگرنه:
        سرچاپ "  رد شد:"، خطا.پیام
    پایان
پایان

تابع ریشه:
    متن := "max_upload: 5368709120\npublic: yes\ncode: 007\n"
    سرچاپ "public از نوع"، یامل.نوع(متن، "public")، "است، پس دریافت منطقی می‌گوید"، یامل.دریافت منطقی(متن، "public")
    سرچاپ "code از نوع"، یامل.نوع(متن، "code")، "است با متن"، یامل.دریافت(متن، "code")
    سرچاپ "دریافت عدد سرریز می‌کند:"، یامل.دریافت عدد(متن، "max_upload")
    سرچاپ "به شکل جیسون:"، یامل.به جیسون(متن)
    بارگذاری(متن)
    بارگذاری("max_upload: 5368709120\npublic: true\ncode: \"007\"\n")
پایان

خروجیpublic از نوع string است، پس دریافت منطقی می‌گوید false code از نوع string است با متن 007 دریافت عدد سرریز می‌کند: 1073741824 به شکل جیسون: {"max_upload": 5368709120, "public": "yes", "code": "007"} رد شد: value does not match the expected type بارگذاری شد: 5368709120 true 007

راه ساختار گونه‌ها را هم برایتان بررسی می‌کند: public: yes به‌جای این‌که نادرست خوانده شود رد می‌شود. نوشتن true و گذاشتن مقدارهایی که باید متن بمانند در نقل‌قول، مثل "007"، باعث می‌شود پرونده برای هر خواننده‌ای یک معنا داشته باشد.

کدام تابع برای کدام کار

کار	به کار ببرید
خواندن چند تنظیم	`دریافت`، `دریافت عدد`، `دریافت منطقی`، `دریافت اعشار`
جدا کردن کلید نبوده از کلید خالی	`دارد`، `دارد کلیدها`
نگاه به ساختار	`نوع`، `طول`، `کلیدها`
کل پرونده در یک ساختار	`به جیسون` و `جیسون.واسریال سازی آسان گیر`
شکل ناشناخته	`کدگشایی` به یک مقدار و `کدگذاری` برای برگشت
نوشتن یامل	`شیء`، `عضو`، یا `برونریزی` از جیسون
پرونده‌های دارای `---`	`تفکیک کردن اسناد`

تابع‌ها

دریافت `Get`

تابع دریافت(text: رشته، path: رشته): رشته

مقدار یک مسیر به شکل متن؛ رشته‌ها بدون نقل‌قول، و مسیر ناموجود یا null رشته‌ی خالی.

encoding-yaml-Query.salam

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

تابع ریشه:
    متن := "app:\n  name: salam\n  port: 8080\n  debug: true\n  ratio: 0.5\n  hosts:\n    - a.example\n    - b.example\n"
    سرچاپ یامل.معتبر(متن)، یامل.دارد(متن، "app.name")، یامل.دارد(متن، "app.user")
    سرچاپ یامل.دریافت(متن، "app.name")، یامل.دریافت عدد(متن، "app.port")، یامل.دریافت منطقی(متن، "app.debug")، یامل.دریافت اعشار(متن، "app.ratio")
    سرچاپ یامل.نوع(متن، "app.hosts")، یامل.طول(متن، "app.hosts")، یامل.دریافت(متن، "app.hosts[1]")
    سرچاپ یامل.کلیدها(متن، "app")
    ناپایا لازم := وکتور {} برگردان وکتور<رشته>
    لازم.بیفزا("app")
    سرچاپ یامل.دارد کلیدها(متن، لازم)
    لازم.بیفزا("db")
    سرچاپ یامل.دارد کلیدها(متن، لازم)
    سرچاپ یامل.به جیسون(متن)
    سرچاپ یامل.تفکیک کردن اسناد("a: 1\n---\nb: 2\n").طول()
پایان

خروجیtrue true false salam 8080 true 0.5 list 2 b.example ["name", "port", "debug", "ratio", "hosts"] true false {"app": {"name": "salam", "port": 8080, "debug": true, "ratio": 0.5, "hosts": ["a.example", "b.example"]}} 2

دارد `Has`

تابع دارد(text: رشته، path: رشته): منطقی

اگر مسیر وجود داشته باشد، درست برمی‌گرداند.

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

دریافت عدد `GetInt`

تابع دریافت عدد(text: رشته، path: رشته): صحیح

عدد صحیح یک مسیر به شکل صحیح ۳۲ بیتی؛ اگر نباشد صفر. عددهای بزرگ‌تر سرریز می‌کنند.

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

دریافت اعشار `GetFloat`

تابع دریافت اعشار(text: رشته، path: رشته): اعشار۶۴

مقدار اعشاری یک مسیر.

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

دریافت منطقی `GetBool`

تابع دریافت منطقی(text: رشته، path: رشته): منطقی

مقدار منطقی یک مسیر: فقط برای true درست است. yes و on رشته‌اند و نادرست می‌دهند.

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

نوع `TypeOf`

تابع نوع(text: رشته، path: رشته): رشته

گونه‌ی مقدار یک مسیر: map، list، string، int، float، bool، null یا اگر نباشد none.

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

طول `Len`

تابع طول(text: رشته، path: رشته): صحیح

تعداد عضوهای فهرست یا کلیدهای شیء در یک مسیر.

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

کلیدها `Keys`

تابع کلیدها(text: رشته، path: رشته): وکتور<رشته>

کلیدهای شیء در یک مسیر؛ مسیر خالی یعنی سطح بالا.

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

دارد کلیدها `HasKeys`

تابع دارد کلیدها(text: رشته، required: وکتور<رشته>): منطقی

اگر همه‌ی کلیدهای داده‌شده در سطح بالای سند باشند، درست برمی‌گرداند؛ برای بررسی پرونده‌ی پیکربندی.

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

کدگشایی `Decode`

تابع کدگشایی(text: رشته، err &: encerr.EncodingError): value.Value

یامل را به یک مقدار پویا تبدیل می‌کند.

encoding-yaml-Build.salam

واردسازی کدگذاری.یامل
واردسازی کدگذاری.مقدار
واردسازی کدگذاری.خطای کدگذاری
واردسازی رشته

تابع ریشه:
    ناپایا اعضا := وکتور {} برگردان وکتور<رشته>
    اعضا.بیفزا(یامل.عضو("name"، "salam"))
    اعضا.بیفزا(یامل.عضو عدد("port"، ۸۰۸۰))
    اعضا.بیفزا(یامل.عضو منطقی("debug"، نادرست))
    اعضا.بیفزا(یامل.عضو اعشار("ratio"، ۰.۲۵))
    ناپایا میزبان‌ها := وکتور {} برگردان وکتور<رشته>
    میزبان‌ها.بیفزا(یامل.رشته یامل("a: b"))
    اعضا.بیفزا(یامل.عضو خام("hosts"، یامل.آرایه(میزبان‌ها)))
    شیء := یامل.شیء(اعضا)
    سرچاپ شیء
    سرچاپ یامل.برونریزی(شیء)
    سرچاپ رشته.شامل است(یامل.برونریزی تب(`{"a": {"b": 1}}`)، "\tb: 1")، یامل.برونریزی سفارشی(`{"a": [1]}`، "    ")
    سرچاپ یامل.اسکیپ("یک: دو")
    سرچاپ یامل.تجزیه("x: 1")
    ناپایا خ := خطای کدگذاری.بدون خطا()
    م := یامل.کدگشایی("شهر: تهران\nجمعیت: 9000000\n"، خ)
    سرچاپ مقدار.به صحیح(مقدار.مقدار کلید(م، "جمعیت"))
    سرچاپ یامل.کدگذاری(م)
پایان

خروجی{"name": "salam", "port": 8080, "debug": false, "ratio": 0.25, "hosts": ["a: b"]} name: salam port: 8080 debug: false ratio: 0.25 hosts: - "a: b" true a: - 1 یک: دو {"x": 1} 9000000 شهر: تهران جمعیت: 9000000