भाषा की बुनियादी बातें

YAML को समझना

YAML एक लोकप्रिय भाषा है. इसका इस्तेमाल, सॉफ़्टवेयर कॉन्फ़िगरेशन की जानकारी देने के लिए किया जाता है. यह स्ट्रक्चर्ड डेटा को दिखाने का एक साफ़ और आसान तरीका है. स्क्रिप्ट की मदद से पहला ऑटोमेशन बनाने से पहले, आपको YAML के बारे में कुछ बुनियादी बातें समझनी होंगी. YAML के बारे में ज़्यादा जानने के लिए, वर्शन 1.1 स्पेसिफ़िकेशन देखें.

की-वैल्यू पेयर

वाईएएमएल दस्तावेज़, मुख्य तौर पर की-वैल्यू पेयर का कलेक्शन होते हैं. इस उदाहरण में, कुंजी 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 स्ट्रक्चर पर एक नज़र डालें, जिसमें चार फ़ील्ड के बारे में बताया गया है:

रेफ़रंस सेक्शन में, उपलब्ध सभी स्ट्रक्चर के लिए स्कीमा की परिभाषाएं दी गई हैं.

किसी स्ट्रक्ट में मौजूद कुंजियों के नाम यूनीक और केस-सेंसिटिव होते हैं.

वैल्यू के टाइप ये हो सकते हैं:

• प्रिमिटिव टाइप: bool, number, string, time वगैरह.
• Struct टाइप: फ़ील्ड का कलेक्शन.
• डेटा टाइप का कलेक्शन. अरे को [] से दिखाया जाता है. उदाहरण के लिए, [string] स्ट्रिंग का एक कलेक्शन है और [Starter] स्टार्टर स्ट्रक्चर का एक कलेक्शन है.
• अन्य खास टाइप: Entity, FieldPath.

हर फ़ील्ड की जानकारी में अहम जानकारी शामिल होती है. जैसे:

• ज़रूरी बनाम ज़रूरी नहीं, इससे पता चलता है कि फ़ील्ड भरना ज़रूरी है या इसे छोड़ा जा सकता है.
• फ़ील्ड डिपेंडेंसी. सिर्फ़ वैकल्पिक फ़ील्ड में डिपेंडेंसी होती हैं. इससे, इस फ़ील्ड का इस्तेमाल करते समय की जाने वाली अतिरिक्त जांचों के बारे में पता चलता है. जैसे, फ़ील्ड B का इस्तेमाल सिर्फ़ तब करें, जब फ़ील्ड A सेट हो या फ़ील्ड A का इस्तेमाल करते समय, फ़ील्ड B या फ़ील्ड C को सेट न करें.
• इस्तेमाल की जा सकने वाली वैल्यू. उदाहरण के लिए, स्ट्रिंग टाइप के Enum फ़ील्ड की वैल्यू का सीमित सेट या नंबर टाइप के फ़ील्ड में इस्तेमाल की जा सकने वाली संख्याओं की रेंज.

टाइप किया गया स्ट्रक्ट

कुछ Structs, समय के शेड्यूल या डिवाइस की स्थिति में बदलाव के आधार पर स्टार्टर दिखा सकते हैं. हर तरह के 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 एक टाइप किया गया स्ट्रक्चर है. इसे type फ़ील्ड में मौजूद अन्य चाइल्ड स्ट्रक्चर, जैसे कि time.schedule या device.state.OnOff से बढ़ाया जाता है, ताकि अलग-अलग फ़ंक्शन उपलब्ध कराए जा सकें. condition और action स्ट्रक्चर भी टाइप किए जाते हैं.

Struct में मौजूद अतिरिक्त फ़ील्ड, चाइल्ड Struct (type) की जानकारी के मुताबिक होने चाहिए. उदाहरण के लिए, type के तौर पर device.state.OnOff का इस्तेमाल करने पर, उस starter स्ट्रक्चर में सिर्फ़ उस टाइप के लिए तय किए गएफ़ील्ड मान्य होते हैं.

Array

YAML में, वैल्यू का कलेक्शन - (डैश के बाद स्पेस) से शुरू होता है. अरे में कई स्ट्रक्चर वैल्यू या कई प्रिमिटिव वैल्यू हो सकती हैं. हालांकि, अरे में मौजूद वैल्यू एक ही तरह की होनी चाहिए.

जब कलेक्शन में सिर्फ़ एक आइटम हो, तो डैश और स्पेस को हटाया जा सकता है:

# 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, state फ़ील्ड के लिए FieldPath है.

# 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