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

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.

ऑटोमेशन स्क्रिप्ट

ऑटोमेशन स्क्रिप्ट सिंटैक्स की खास जानकारी को स्कीमा कहा जाता है.

ऑटोमेशन स्कीमा में कुछ डेटा स्ट्रक्चर तय किए गए हैं:

• एक की-वैल्यू पेयर को फ़ील्ड कहा जाता है.
• स्कीमा के हिसाब से तय किए गए फ़ील्ड के कलेक्शन को स्ट्रक्चर कहा जाता है.

Struct

ऑटोमेशन स्क्रिप्टिंग भाषा, कई स्टैंडर्ड 'ब्लॉक' या डेटा स्ट्रक्चर तय करती है. इन्हें स्ट्रक्चर कहा जाता है.

automation स्ट्रक्चर पर एक नज़र डालें, जिसमें चार फ़ील्ड तय किए गए हैं:

कुंजी	स्ट्रीम किस तरह की है	जानकारी
name	स्ट्रिंग	ज़रूरी नहीं. ऑटोमेशन का नाम. यह उपयोगकर्ताओं को नहीं दिखता. यह सिर्फ़ डेवलपर के लिए है.
starters	[Starter]	ज़रूरी है. स्टार्टर की सूची.
condition	स्थिति	ज़रूरी नहीं. स्थिति.
actions	[कार्रवाई]	ज़रूरी है. कार्रवाइयों की सूची.

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

किसी स्ट्रक्चर में, की के नाम यूनीक होते हैं और केस-सेंसिटिव होते हैं.

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

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

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

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

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

कुछ स्ट्रक्चर, समय के शेड्यूल या डिवाइस की स्थिति में बदलाव के आधार पर स्टार्टर दिखा सकते हैं. हर तरह के 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 स्ट्रक्चर भी टाइप किए जाते हैं.

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

प्रिमिटिव

ऑटोमेशन स्क्रिप्ट के स्कीमा में, ये प्राइमिटिव डेटा टाइप इस्तेमाल किए जा सकते हैं:

बूल	true false
नंबर	पूर्णांक या दशमलव वाली संख्या
स्ट्रिंग	सादा लेख खास मामलों को छोड़कर, स्ट्रिंग को कोटेशन में रखने की ज़रूरत नहीं होती.
तारीख	महीना और दिन. फ़ॉर्मैट MM-DD या MM/DD होना चाहिए. 09/01 09-01
समय	दिन का समय. यह घड़ी का समय या सौर समय हो सकता है. घड़ी के समय के लिए, AM/PM फ़ॉर्मैट या 24H फ़ॉर्मैट का इस्तेमाल किया जा सकता है. सेकंड की वैल्यू देना ज़रूरी नहीं है. सौर समय के लिए, sunrise और sunset कीवर्ड हैं. इसके बाद, ऑफ़सेट (अवधि के हिसाब से) हो सकता है. 12:30 am 13:00:01 sunrise / sunset sunset+30min / sunset-1hour
DateTime	साल, महीना, दिन, और दिन का समय. तारीख और समय के बीच खाली जगह होनी चाहिए. तारीख का फ़ॉर्मैट YYYY-MM-DD या YYYY/MM/DD होना चाहिए. समय का फ़ॉर्मैट, [समय](#time) एट्रिब्यूट के फ़ॉर्मैट जैसा ही होना चाहिए. टाइम ज़ोन का इस्तेमाल नहीं किया जा सकता. 2022/01/01 14:00 2022-12-31 sunrise+30min
कामकाजी दिन (वीकडे)	MONDAY (या MON) TUESDAY (या TUE) WEDNESDAY (या WED) THURSDAY (या THU) FRIDAY (या FRI) SATURDAY (या SAT) SUNDAY (या SUN)
कुल समय	कोई समयावधि. 30min 1hour 20sec 1hour10min20sec
ColorHex	छह अंकों का हेक्साडेसिमल कोड, जो किसी रंग को दिखाता है. कोई लीडिंग # नहीं है. FFFFFF B5D2A1 DFA100
तापमान	सामान्य तापमान का डेटा. तापमान का आकलन दिखाने के लिए, वैल्यू में हमेशा 'C' या 'F' जोड़ें. 20.5C 90F
ColorTemperature	केल्विन में कलर टेंपरेचर. 5000K

रंग

रंगों को तीन में से किसी एक तरीके से तय किया जा सकता है - ColorHex या ColorTemperature प्राइमटिव टाइप का इस्तेमाल करके या फिर कंपाउंड टाइप SpectrumHSV का इस्तेमाल करके.

SpectrumHSV

SpectrumHSV टाइप, तीन अंकों वाले तीन फ़ील्ड का इस्तेमाल करके किसी रंग की जानकारी देता है:

• ह्यू, रंग की तरंग दैर्ध्य से जुड़ा होता है.
• Saturation से रंग की तीव्रता का पता चलता है.
• वैल्यू से पता चलता है कि रंग कितना हल्का या गहरा है.

डाइनैमिक

कभी-कभी, किसी कुंजी का डेटा टाइप तय नहीं होता. यह अन्य फ़ील्ड की वैल्यू के आधार पर, प्राइमिटिव टाइप में से कोई एक हो सकता है.

डाइनैमिक डेटा टाइप फ़ील्ड का उदाहरण 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