Module: OpenHAB::Core::Items::Semantics
- Included in:
- Item
- Defined in:
- lib/openhab/core/items/semantics.rb,
lib/openhab/core/items/semantics/provider.rb,
lib/openhab/core/items/semantics/semantic_tag.rb
Overview
Module for implementing semantics helper methods on Item in order to easily navigate the Semantic Model in your scripts. This can be extremely useful to find related items in rules that are executed for any member of a group.
Wraps org.openhab.core.model.script.actions.Semantics as well as adding a few additional convenience methods. Also includes classes for each semantic tag.
Be warned that the Semantic model is stricter than can actually be described by tags and groups on an Item. It makes assumptions that any given item only belongs to one semantic type (Location, Equipment, Point).
#Enumerable helper methods
Enumerable helper methods are also provided to complement the semantic model. These methods can be chained together to find specific item(s) based on custom tags or group memberships that are outside the semantic model.
The Enumerable helper methods apply to:
- GroupItem#members and GroupItem#all_members. This includes semantic #location and #equipment because they are also group items. An exception is for Equipments that are an item (not a group)
- Array of items, such as the return value of Enumerable#equipments, Enumerable#locations, Enumerable#points, Enumerable#tagged, Enumerable#not_tagged, Enumerable#member_of, Enumerable#not_member_of, Enumerable#members methods, etc.
- items[] hash which contains all items in the system.
#Semantic Classes
Each Semantic Tag has a corresponding class within the org.openhab.core.semantics class hierarchy. These "semantic classes" are available as constants in the Semantics module with the corresponding name. The following table illustrates the semantic constants:
Semantic Constant | openHAB's Semantic Class |
---|---|
Semantics::LivingRoom |
org.openhab.core.semantics.model.location.LivingRoom |
Semantics::Lightbulb |
org.openhab.core.semantics.model.equipment.Lightbulb |
Semantics::Control |
org.openhab.core.semantics.model.point.Control |
Semantics::Switch |
org.openhab.core.semantics.model.point.Switch |
Semantics::Power |
org.openhab.core.semantics.model.property.Power |
... | ... |
These constants can be used as arguments to the #points, Enumerable#locations and Enumerable#equipments methods to filter their results. They can also be compared against the return value of #semantic_type, #location_type, #equipment_type, #point_type, and #property_type. They can even be used with DSL::Items::ItemBuilder#tag.
All of the tag objects implement SemanticTag.
For example, to get the synonyms for Semantics::Lightbulb
in German:
Semantics::Lightbulb.synonyms(java.util.Locale::GERMAN)
#Adding Custom Semantic Tags
openHAB 4.0 supports adding custom semantic tags to augment the standard set of tags to better suit your particular requirements.
For more information, see Semantics.add
Defined Under Namespace
Modules: SemanticTag Classes: Provider
Constant Summary collapse
- Tag =
Deprecated.
Since openHAB 4.0, SemanticTag is the interface that all tags implement. Tags are simple instances, instead of another interface in a hierarchical structure.
This is a marker interface for all semantic tag classes.
- org.openhab.core.semantics.Tag
- Location =
This is the parent tag for all tags that represent a Location.
- SemanticTag
- Equipment =
This is the parent tag for all tags that represent an Equipment.
- SemanticTag
- Point =
This is the parent tag for all tags that represent a Point.
- SemanticTag
- Property =
This is the parent tag for all property tags.
- SemanticTag
Instance Attribute Summary collapse
-
#equipment ⇒ Item?
readonly
Gets the related Equipment Item of this Item.
-
#equipment_type ⇒ SemanticTag?
readonly
Returns the sub-tag of Equipment related to this Item.
-
#location ⇒ Item?
readonly
Gets the related Location Item of this Item.
-
#location_type ⇒ SemanticTag?
readonly
Returns the sub-tag of Location related to this Item.
-
#point_type ⇒ SemanticTag?
readonly
Returns the sub-tag of Point this Item is tagged with.
-
#property_type ⇒ SemanticTag?
readonly
Returns the sub-tag of Property this Item is tagged with.
-
#semantic_type ⇒ SemanticTag?
readonly
Returns the SemanticTag this Item is tagged with.
Class Method Summary collapse
-
.add(label: nil, synonyms: "", description: "", **tags) ⇒ Array<SemanticTag>
Adds custom semantic tags.
-
.lookup(id, locale = java.util.Locale.default) ⇒ SemanticTag?
Finds a semantic tag using its name, label, or synonyms.
-
.remove(*tags, recursive: false) ⇒ Array<SemanticTag>
Removes custom semantic tags.
-
.tags ⇒ Array<SemanticTag>
Returns all available Semantic tags.
Instance Method Summary collapse
-
#equipment? ⇒ true, false
Checks if this Item is an Equipment.
-
#location? ⇒ true, false
Checks if this Item is a Location.
-
#point? ⇒ true, false
Checks if this Item is a Point.
-
#points(*point_or_property_types) ⇒ Array<Item>
Return the related Point Items.
-
#semantic? ⇒ true, false
Checks if this Item has any semantic tags.
Instance Attribute Details
#equipment ⇒ Item? (readonly)
472 473 474 |
# File 'lib/openhab/core/items/semantics.rb', line 472 def equipment Actions::Semantics.get_equipment(self)&.then(&Proxy.method(:new)) end |
#equipment_type ⇒ SemanticTag? (readonly)
Returns the sub-tag of Equipment related to this Item.
In other words, the #semantic_type of this Item's Equipment.
485 486 487 |
# File 'lib/openhab/core/items/semantics.rb', line 485 def equipment_type translate_tag(Actions::Semantics.get_equipment_type(self)) end |
#location ⇒ Item? (readonly)
446 447 448 |
# File 'lib/openhab/core/items/semantics.rb', line 446 def location Actions::Semantics.get_location(self)&.then(&Proxy.method(:new)) end |
#location_type ⇒ SemanticTag? (readonly)
Returns the sub-tag of Location related to this Item.
In other words, the #semantic_type of this Item's Location.
459 460 461 |
# File 'lib/openhab/core/items/semantics.rb', line 459 def location_type translate_tag(Actions::Semantics.get_location_type(self)) end |
#point_type ⇒ SemanticTag? (readonly)
Returns the sub-tag of Point this Item is tagged with.
496 497 498 |
# File 'lib/openhab/core/items/semantics.rb', line 496 def point_type translate_tag(Actions::Semantics.get_point_type(self)) end |
#property_type ⇒ SemanticTag? (readonly)
Returns the sub-tag of Property this Item is tagged with.
507 508 509 |
# File 'lib/openhab/core/items/semantics.rb', line 507 def property_type translate_tag(Actions::Semantics.get_property_type(self)) end |
#semantic_type ⇒ SemanticTag? (readonly)
Returns the SemanticTag this Item is tagged with.
It will only return the first applicable Tag, preferring a sub-tag of Location, Equipment, or Point first, and if none of those are found, looks for a Property.
521 522 523 |
# File 'lib/openhab/core/items/semantics.rb', line 521 def semantic_type translate_tag(Actions::Semantics.get_semantic_type(self)) end |
Class Method Details
.add(**tags) ⇒ Array<SemanticTag> .add(label: nil, synonyms: "", description: "", **tags) ⇒ Array<SemanticTag>
Adds custom semantic tags.
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 |
# File 'lib/openhab/core/items/semantics.rb', line 269 def add(label: nil, synonyms: "", description: "", **tags) raise ArgumentError, "Tags must be specified" if tags.empty? if (tags.length > 1) && !(label.nil? && synonyms.empty? && description.empty?) raise ArgumentError, "Additional options can only be specified when creating one tag" end synonyms = Array.wrap(synonyms).map { |s| s.to_s.strip } tags.filter_map do |name, parent| if (existing_tag = lookup(name)) logger.warn("Tag already exists: #{existing_tag.inspect}") next end unless parent.is_a?(SemanticTag) parent_tag = lookup(parent) raise ArgumentError, "Unknown parent: #{parent}" unless parent_tag parent = parent_tag end new_tag = org.openhab.core.semantics.SemanticTagImpl.new("#{parent.uid}_#{name}", label, description, synonyms) Provider.instance.add(new_tag) lookup(name) end end |
.lookup(id, locale = java.util.Locale.default) ⇒ SemanticTag?
Finds a semantic tag using its name, label, or synonyms.
209 210 211 212 213 214 215 216 217 218 219 220 |
# File 'lib/openhab/core/items/semantics.rb', line 209 def lookup(id, locale = java.util.Locale.default) id = id.to_s # Java21 added #first method, which overrides Ruby's #first. # It throws an error if the list is Empty instead of returning nil. # So we use #ruby_first to ensure we get Ruby's behaviour tag_class = service.get_by_label_or_synonym(id, locale).ruby_first || Provider.registry.get_tag_class_by_id(id) return unless tag_class Provider.registry.get(Provider.registry.class.build_id(tag_class)) end |
.remove(*tags, recursive: false) ⇒ Array<SemanticTag>
Removes custom semantic tags.
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 |
# File 'lib/openhab/core/items/semantics.rb', line 312 def remove(*tags, recursive: false) tags.flat_map do |tag| tag = lookup(tag) unless tag.is_a?(SemanticTag) next unless tag provider = Provider.registry.provider_for(tag) unless provider.is_a?(ManagedProvider) raise FrozenError, "Cannot remove item #{tag} from non-managed provider #{provider.inspect}" end children = [] Provider.registry.providers.grep(ManagedProvider).each do |managed_provider| managed_provider.all.each do |existing_tag| next unless existing_tag.parent_uid == tag.uid raise ArgumentError, "Cannot remove #{tag} because it has children" unless recursive children += remove(existing_tag, recursive:) end end remove_const(tag.name) if provider.remove(tag.uid) && const_defined?(tag.name) [tag] + children end.compact end |
.tags ⇒ Array<SemanticTag>
Returns all available Semantic tags
197 198 199 |
# File 'lib/openhab/core/items/semantics.rb', line 197 def tags Provider.registry.all.to_a end |
Instance Method Details
#equipment? ⇒ true, false
Checks if this Item is an Equipment
This is implemented as checking if the item's #semantic_type is an Equipment. I.e. an Item has a single #semantic_type.
412 413 414 |
# File 'lib/openhab/core/items/semantics.rb', line 412 def equipment? Actions::Semantics.equipment?(self) end |
#location? ⇒ true, false
Checks if this Item is a Location
This is implemented as checking if the item's #semantic_type is a Location. I.e. an Item has a single #semantic_type.
400 401 402 |
# File 'lib/openhab/core/items/semantics.rb', line 400 def location? Actions::Semantics.location?(self) end |
#point? ⇒ true, false
Checks if this Item is a Point
This is implemented as checking if the item's #semantic_type is a Point. I.e. an Item has a single #semantic_type.
423 424 425 |
# File 'lib/openhab/core/items/semantics.rb', line 423 def point? Actions::Semantics.point?(self) end |
#points(*point_or_property_types) ⇒ Array<Item>
Return the related Point Items.
Searches this Equipment Item for Points that are tagged appropriately.
If called on a Point Item, it will automatically search for sibling Points (and remove itself if found).
552 553 554 555 556 557 558 559 |
# File 'lib/openhab/core/items/semantics.rb', line 552 def points(*point_or_property_types) return members.points(*point_or_property_types) if equipment? || location? # automatically search the parent equipment (or location?!) for sibling points result = (equipment || location)&.points(*point_or_property_types) || [] result.delete(self) result end |
#semantic? ⇒ true, false
Checks if this Item has any semantic tags
432 433 434 |
# File 'lib/openhab/core/items/semantics.rb', line 432 def semantic? !!semantic_type end |