ভাষার প্রাথমিক বিষয়

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.

অটোমেশন স্ক্রিপ্ট

অটোমেশন স্ক্রিপ্ট সিনট্যাক্সের স্পেসিফিকেশনকে স্কিমা বলা হয়।

অটোমেশন স্কিমা কয়েকটি ডেটা স্ট্রাকচারকে সংজ্ঞায়িত করে:

• একটি কী-ভ্যালু পেয়ারকে ফিল্ড বলা হয়।
• স্কিমা দ্বারা সংজ্ঞায়িত ফিল্ডের সংগ্রহকে Struct বলা হয়।

স্ট্রাক্ট

অটোমেশন স্ক্রিপ্টিং ভাষা বেশ কয়েকটি স্ট্যান্ডার্ড 'ব্লক' বা ডেটা স্ট্রাকচারকে সংজ্ঞায়িত করে, যাকে Structs বলা হয়।

automation Struct-এ একবার চোখ বুলিয়ে নিন, যা চারটি ফিল্ডকে সংজ্ঞায়িত করে:

রেফারেন্স বিভাগ থেকে উপলভ্য সব স্ট্রাক্টের স্কিমা সংজ্ঞা পাওয়া যায়।

কোনও নির্দিষ্ট Struct-এর মধ্যে 'কী'-এর নাম অনন্য হয় এবং ছোট ও বড় হাতের অক্ষরের মধ্যে পার্থক্য করা হয়।

সম্ভাব্য ভ্যালুর ধরনগুলি হল:

• একটি প্রিমিটিভ টাইপ: বুল, নম্বর, স্ট্রিং, সময় এবং আরও অনেক কিছু।
• Struct-এর ধরন: ফিল্ডের সংগ্রহ।
• ডেটার ধরনের অ্যারে। এরে [] দ্বারা চিহ্নিত করা হয়। যেমন, [string] হল স্ট্রিংয়ের অ্যারে এবং [Starter] হল স্টার্টার স্ট্রাক্টের অ্যারে।
• অন্যান্য বিশেষ ধরন: Entity, FieldPath.

প্রতিটি ফিল্ডের বিবরণে গুরুত্বপূর্ণ তথ্য থাকে, যার মধ্যে রয়েছে:

• প্রয়োজনীয় বনাম ঐচ্ছিক, ফিল্ডটি পূরণ করা বাধ্যতামূলক নাকি সেটি এড়িয়ে যাওয়া যাবে তা নির্দেশ করে।
• ফিল্ড ডিপেন্ডেন্সি। শুধুমাত্র ঐচ্ছিক ফিল্ডের ডিপেন্ডেন্সি আছে। এই ফিল্ড ব্যবহার করার সময় অতিরিক্ত চেক করার ব্যাপারে এটি বর্ণনা করে, যেমন ফিল্ড A সেট করা থাকলে তবেই ফিল্ড B ব্যবহার করুন, অথবা ফিল্ড 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 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 হল state ফিল্ডের FieldPath।

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

প্রয়োজনীয় আইটেম পেতে অন্যান্য FieldPaths-এর একাধিক লেভেলের প্রয়োজন হতে পারে এবং স্টার্টার ও অ্যাকশনের মধ্যে ফর্ম্যাট আলাদা হয়।

স্টার্টাররা ডট নোটেশন ব্যবহার করে, একই ফিল্ডে সম্পূর্ণ পাথ সহ। এটি মূলত স্টার্টার লজিকে তুলনা করার উদ্দেশ্যে করা হয়। যেমন, স্টার্টার হিসেবে কালার টেম্পারেচার ব্যবহার করতে, আপনি 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