اصول اولیه زبان

آشنایی با YAML

YAML زبان محبوبی است که برای مشخص کردن پیکربندی نرم‌افزار استفاده می‌شود. این قالب روشی واضح و قابل‌خواندن برای انسان برای نمایش اطلاعات ساختاریافته ارائه می‌دهد. در اینجا چند نکته اساسی وجود دارد که باید درباره YAML بدانید قبل‌از اینکه اولین خودکارسازی بااستفاده از دستورات را ایجاد کنید. برای آشنایی بیشتر با YAML به‌طور کلی، مشخصات نسخه ۱.۱ را ببینید.

جفت‌های کلید-مقدار

اسناد YAML اساساً مجموعه‌ای از جفت‌های کلید-مقدار هستند. در مثال زیر، کلید name و مقدار TV on lights off است. کلید و مقدار با دونقطه و سپس فاصله از هم جدا می‌شوند. هر دو نویسه برای YAML خوش‌ساخت لازم است.

name: TV on lights off

مقادیر

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

رشته‌ها

اگر مقدار رشته با یکی از نویسه‌های زیر شروع شود: [، {، "، ' یا #، یا رشته حاوی : (دو نقطه و به‌دنبال آن فاصله) باشد، باید در گیومه قرار گیرد.

هم علامت نقل‌قول تکی و هم دوتایی پذیرفته می‌شود، اما علامت نقل‌قول پایانی باید با علامت نقل‌قول آغازین مطابقت داشته باشد.

نقل‌قول صحیح:

name: 'TV on lights off'

name: "TV on lights off"

نقل‌قول نادرست (نقل‌قول‌های نامطابق):

name: 'TV on lights off"

استفاده از گیومه برای همه انواع دیگر رشته‌ها اختیاری است.

اگر به رشته چندخطی نیاز دارید، بخش مشخصات YAML درباره اسکالرهای چندخطی را ببینید.

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

جفت‌های کلید-مقدار تودرتو

در اینجا مقدار کلید metadata فهرستی از دو جفت کلید-مقدار است (name و description):

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

تورفتگی

‫YAML از تورفتگی برای نشان دادن ساختار استفاده می‌کند. در مثال قبلی، name و description تورفتگی دارند (با دو فاصله) تا نشان دهند که این‌ها فرزندان کلید metadata هستند.

تورفتگی در YAML سخت‌گیرانه است. ساختار فرزند باید تورفتگی عمیق‌تری نسبت به والد خود داشته باشد، و جفت‌های کلید-مقدار هم‌سطح باید تورفتگی یکسانی داشته باشند.

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

چندین مقدار

اگر کلید داده‌شده چند مقدار داشته باشد، هر مقدار در خط جدیدی فهرست می‌شود و هر خط با خط تیره و فاصله شروع می‌شود. در مثال زیر، دو فهرست وجود دارد:

1. یک خودکارسازی می‌تواند چند starters داشته باشد و بنابراین اولین آغازگر با خط تیره و فاصله شروع می‌شود.
2. weekday می‌تواند چند مقدار داشته باشد و بنابراین، هر مقدار بیشتر تورفتگی دارد و با خط تیره و فاصله شروع می‌شود.

starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

نظرات

هر نوشتاری که بعداز # بیاید به‌عنوان نظر درنظر گرفته می‌شود و موتور خودکارسازی آن را نادیده می‌گیرد.

خطی که با # شروع می‌شود نظر است.

نظر ممکن است در همان خط محتوای دستورات ظاهر شود، اما # باید با یک فاصله شروع شود.

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

دستورگان خودکارسازی

مشخصات نحو متن «خودکارسازی‌ها» طرح‌واره نامیده می‌شود.

طرح‌واره «خودکارسازی‌ها» چند ساختار داده را تعریف می‌کند:

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

ساختار

زبان دستورگان‌نویسی خودکارسازی چندین «بلوک» یا ساختار داده استاندارد را تعریف می‌کند که به آن‌ها ساختار گفته می‌شود.

به «ساخت» automation نگاه کنید که چهار فیلد را تعریف می‌کند:

بخش مرجع تعاریف طرح‌واره را برای همه «ساختارها»ی دردسترس ارائه می‌دهد.

نام‌های کلید در یک Struct داده‌شده منحصربه‌فرد و حروف‌حساس هستند.

انواع مقادیر ممکن عبارتند از:

• نوع اولیه: بولی، عدد، رشته، زمان، و غیره.
• نوع «ساخت»: مجموعه‌ای از فیلدها.
• آرایه‌ای از نوع داده. آرایه با [] نشان داده می‌شود. برای مثال، [string] آرایه‌ای از رشته‌ها است و [Starter] آرایه‌ای از «ساختارهای آغازگر» است.
• انواع خاص دیگر: Entity،‏ FieldPath.

شرح هر «فیلد» حاوی اطلاعات مهمی است، ازجمله:

• الزامی درمقابل اختیاری، که نشان می‌دهد فیلد اجباری است یا می‌توان از آن رد شد.
• وابستگی فیلد. فقط فیلدهای اختیاری وابستگی دارند. این بخش بررسی‌های اضافی را هنگام استفاده از این فیلد شرح می‌دهد، مانند فقط درصورتی از فیلد «ب» استفاده کنید که فیلد «الف» تنظیم شده باشد، یا وقتی از فیلد «الف» استفاده می‌شود، فیلد «ب» یا فیلد «ج» را تنظیم نکنید.
• مقادیر ممکن. برای مثال، مجموعه مقدار محدود Enum Field از نوع رشته، یا گستره‌ای از اعداد که ممکن است در Field از نوع عدد استفاده شود.

ساختار تایپ‌شده

برخی‌از «ساختارها» می‌توانند نشان‌دهنده آغازگرهایی براساس زمان‌بندی یا تغییر وضعیت دستگاه باشند. هر نوع starter باید مجموعه متمایزی از «فیلدها» را ارائه دهد.

# A time schedule starter.
starter:
  type: time.schedule
  at: 10:00

# A device state change starter.
starter:
  type: device.state.OnOff
  device: TV - Living Room
  state: on
  is: true

‫starter یک Typed Struct است که توسط Structهای فرزند دیگر در فیلد type گسترش می‌یابد، مانند time.schedule یا device.state.OnOff، تا عملکردهای مختلفی را ارائه دهد. ‫condition و action Structs نیز Typed هستند.

فیلدهای اضافی در Struct باید از مشخصات Struct فرزند (type) پیروی کنند. برای مثال، وقتی از device.state.OnOff به‌عنوان type استفاده می‌شود، فقط فیلدهای مشخص‌شده برای آن نوع در آن starter Struct معتبر هستند.

آرایه

در YAML، آرایه‌ای از مقادیر با - (خط تیره و سپس فاصله) شروع می‌شود. آرایه می‌تواند چند مقدار Struct یا چند مقدار Primitive داشته باشد. اما مقادیر موجود در آرایه باید از یک نوع باشند.

وقتی آرایه حاوی یک مورد است، می‌توانید خط تیره و فاصله را حذف کنید:

# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
  at: sunset
- type: time.schedule
  at: sunrise

# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
  type: time.schedule
  at: sunset

آرایه‌های چندبعدی، مثل [[1, 2], [3, 4]]، در اسکریپت‌نویسی خودکارسازی پشتیبانی نمی‌شوند. تجزیه‌کننده زبان به‌طور خودکار آرایه چندبعدی را به آرایه تک‌بعدی تبدیل می‌کند، در این مورد، [1, 2, 3, 4].

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

بدوی

انواع داده‌های اولیه زیر توسط طرح‌واره دستورات «خودکارسازی‌ها» پشتیبانی می‌شود:

رنگ

رنگ‌ها را می‌توان به یکی از سه روش مشخص کرد - بااستفاده از انواع اصلی ColorHex یا ColorTemperature، یا نوع مرکب SpectrumHSV.

SpectrumHSV

نوع SpectrumHSV رنگ را بااستفاده از سه فیلد عددی مشخص می‌کند:

• رنگ‌مایه با طول موج رنگ مطابقت دارد.
• اشباع رنگ نشان‌دهنده شدت رنگ است.
• مقدار نشان‌دهنده روشنی یا تیرگی نسبی رنگ است.

پویا

گاهی اوقات، نوع داده کلید ثابت نیست. این نوع می‌تواند یکی از انواع اولیه باشد، براساس مقادیر فیلدهای دیگر.

نمونه‌ای از فیلد نوع داده پویا is است. نوع واقعی با مقادیر فیلدهای type و state تعیین می‌شود.

# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false

نهاد

قالب «رشته» خاص برای شناسایی منحصربه‌فرد نهاد تحت مالکیت کاربر، مثل دستگاه یا اتاق.

دستگاه رایج‌ترین نهاد مورداستفاده در «خودکارسازی‌ها» است. قالب رشته نهاد device name - room name است.

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

قالب «رشته» خاصی که برای یافتن بخشی از داده‌ها در بار داده استفاده می‌شود. در مثال زیر، currentVolume عبارت است از FieldPath برای فیلد state.

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

سایر FieldPathها ممکن است برای رسیدن به مورد لازم به چندین سطح نیاز داشته باشند، و قالب بین آغازگر و کنش متفاوت است.

آغازگرها از نشانه‌گذاری نقطه‌ای استفاده می‌کنند و کل مسیر در یک فیلد قرار دارد. این کار عمدتاً برای مقایسه در منطق آغازگر انجام می‌شود. برای مثال، برای استفاده از دمای رنگ به‌عنوان آغازگر، از color.colorTemperature برای وضعیت استفاده می‌کنید:

starters:
- type: device.state.ColorSetting
  device: My Device - Room Name
  state: color.colorTemperature
  is: 2000K

اما کنش‌ها از فیلدهای تودرتو استفاده می‌کنند. برای تغییر رنگ لامپ به آبی، به‌جای color.name و is: blue، باید این کار را انجام دهید:

actions:
- type: device.command.ColorAbsolute
  devices: My Device - Room Name
  color:
    name: blue