openhab-scripting 4.37.0 → 4.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 152174c3766a83b620a0ec7df6e692bb914e187c788d9c5eecfcedd42bfd641c
-  data.tar.gz: 44084d3557abd293faf97858470414cf5f3dd65e07faa8f74e8f40e0d6ea8edb
+  metadata.gz: 1fb1294914e9c3e343bef8f0c1aaca327dbaa5875d446ec3e507edc1f390c9c9
+  data.tar.gz: be121541f849f733505c6180557f88fdd98869d89e0a593c6fc48db0e7e6daf5
 SHA512:
-  metadata.gz: 617deb9b4f75a92a407cf8db6ff695f409ac5f006690751c10100919d414851dc83758ec0560badf3d40097cc896d86de132a215d22a3f505b8e97bff26a8ad2
-  data.tar.gz: 5a2c037047ce9db79d57a153e5df94c631144d511ac716b1862a8a6c4fc567d01c6efa15d93583f2bc80a792c47c85e30dda65ec481a1f14f6a588765638d56f
+  metadata.gz: e6af3e7152dd02c9d98dea19f9bcaa4f474a20daac090941c1121705d177afec2498a2704462645d51b6e4e055efda1f0431702c0f7c6f126718b7994ef6baad
+  data.tar.gz: f9af8246710e44dc86719d10ba2577003293640e1c11885c054da9d23d0be8746e1103151c173672ddfab96ae218f5d717318ab72d628a194f7a243647ea885d

data/lib/openhab/dsl/items/ensure.rb

@@ -73,6 +73,13 @@ module OpenHAB
           @item = item
         end
 
+        # @!visibility private
+        # this is explicitly defined, instead of aliased, because #command
+        # doesn't actually exist as a method, and will go through method_missing
+        def <<(command)
+          command(command)
+        end
+
         # activate +ensure_states+ before forwarding to the wrapped object
         def method_missing(method, *args, &block)
           return super unless @item.respond_to?(method)

data/lib/openhab/dsl/items/generic_item.rb

@@ -2,6 +2,7 @@
 
 require 'openhab/dsl/items/metadata'
 require 'openhab/dsl/items/persistence'
+require 'openhab/dsl/items/semantics'
 
 require_relative 'item_equality'
 
@@ -10,14 +11,17 @@ module OpenHAB
     module Items
       java_import org.openhab.core.items.GenericItem
 
-      # Adds methods to core OpenHAB DimmerItem type to make it more natural in
+      # Adds methods to core OpenHAB GenericItem type to make it more natural in
       # Ruby
+      #
+      # @see https://www.openhab.org/javadoc/latest/org/openhab/core/items/genericitem
       class GenericItem
         include Log
         include ItemEquality
 
         prepend Metadata
         prepend Persistence
+        include Semantics
 
         # rubocop:disable Naming/MethodName these mimic Java fields, which are
         # actually methods

data/lib/openhab/dsl/items/group_item.rb

@@ -39,73 +39,7 @@ module OpenHAB
             group.name
           end
 
-          # Send a command to each member of the group
-          #
-          # @return [GroupMembers] +self+
-          def command(command)
-            each { |item| item << command }
-          end
           alias << command
-
-          # @!method refresh
-          #   Send the +REFRESH+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method on
-          #   Send the +ON+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method off
-          #   Send the +OFF+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method up
-          #   Send the +UP+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method down
-          #   Send the +DOWN+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method stop
-          #   Send the +STOP+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method move
-          #   Send the +MOVE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method increase
-          #   Send the +INCREASE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method desrease
-          #   Send the +DECREASE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method play
-          #   Send the +PLAY+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method pause
-          #   Send the +PAUSE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method rewind
-          #   Send the +REWIND+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method fast_forward
-          #   Send the +FASTFORWARD+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method next
-          #   Send the +NEXT+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method previous
-          #   Send the +PREVIOUS+ command to each member of the group
-          #   @return [GroupMembers] +self+
         end
 
         include Enumerable
@@ -113,6 +47,17 @@ module OpenHAB
 
         remove_method :==
 
+        # Override Enumerable because we want to send them to the base item if possible
+        #
+        # @return [GroupMembers] +self+
+        %i[command update].each do |method|
+          define_method(method) do |command|
+            return base_item.__send__(method, command) if base_item
+
+            super(command)
+          end
+        end
+
         #
         # Get an Array-like object representing the members of the group
         #
@@ -167,6 +112,7 @@ module OpenHAB
           super
         end
 
+        # Is this ever called?
         # give the base item type a chance to format commands
         # @!visibility private
         def format_type(command)

data/lib/openhab/dsl/items/items.rb

@@ -69,13 +69,20 @@ module OpenHAB
               end                                                                                       # end
             RUBY
 
-            logger.trace("Defining GroupItem::GroupMembers##{command} for #{value}")
-            GroupItem::GroupMembers.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            logger.trace("Defining Enumerable##{command} for #{value}")
+            Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
               def #{command}        # def on
                 each(&:#{command})  #   each(&:on)
               end                   # end
             RUBY
 
+            # Override the inherited methods from Enumerable and send it to the base_item
+            GroupItem.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{command}                 # def on
+                method_missing(:#{command})  #   method_missing(:on)
+              end                            # end
+            RUBY
+
             logger.trace("Defining ItemCommandEvent##{command}? for #{value}")
             MonkeyPatch::Events::ItemCommandEvent.class_eval <<~RUBY, __FILE__, __LINE__ + 1
               def #{command}?        # def refresh?

data/lib/openhab/dsl/items/numeric_item.rb

@@ -19,11 +19,26 @@ module OpenHAB
         def self.included(klass)
           klass.prepend ItemEquality # make sure this is first
           klass.extend Forwardable
-          klass.delegate %i[+ - * / % | to_d to_f to_i to_int] => :state
+          klass.delegate %i[+ - * / % to_d to_f to_i to_int] => :state
           # remove the JRuby default == so that we can inherit the Ruby method
           klass.remove_method :==
         end
 
+        #
+        # Convert state to a Quantity by calling state (DecimalType)#|
+        # Raise a NoMethodError if state is nil (NULL or UNDEF) instead of delegating to it.
+        # because nil#| would return true, causing an unexpected result
+        #
+        # @param [Unit, String] other the unit to convert to
+        #
+        # @return [QuantityType] the QuantityType in the given unit
+        #
+        def |(other)
+          raise NoMethodError, 'State is nil' unless state?
+
+          state.|(other)
+        end
+
         #
         # Check if NumericItem is truthy? as per defined by library
         #

data/lib/openhab/dsl/items/semantics/enumerable.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Additions to Enumerable to allow easily filtering and commanding groups of items
+module Enumerable
+  # Returns a new array of items that have at least one of the given tags
+  def tagged(*tags)
+    reject { |i| (tags & i.tags.to_a).empty? }
+  end
+
+  # Returns a new array of items that do not have any of the given tags
+  def not_tagged(*tags)
+    select { |i| (tags & i.tags.to_a).empty? }
+  end
+
+  # Returns a new array of items that are a member of at least one of the given groups
+  def member_of(*groups)
+    reject { |i| (groups.map(&:name) & i.group_names).empty? }
+  end
+
+  # Returns a new array of items that are not a member of any of the given groups
+  def not_member_of(*groups)
+    select { |i| (groups.map(&:name) & i.group_names).empty? }
+  end
+
+  # Send a command to every item in the collection
+  def command(command)
+    each { |i| i.command(command) }
+  end
+
+  # Update the state of every item in the collection
+  def update(state)
+    each { |i| i.update(state) }
+  end
+
+  # Returns the group members the elements
+  def members
+    select { |e| e.respond_to? :members }.flat_map(&:members)
+  end
+
+  # @!method refresh
+  #   Send the +REFRESH+ command to every item in the collection
+
+  # @!method on
+  #   Send the +ON+ command to every item in the collection
+
+  # @!method off
+  #   Send the +OFF+ command to every item in the collection
+
+  # @!method up
+  #   Send the +UP+ command to every item in the collection
+
+  # @!method down
+  #   Send the +DOWN+ command to every item in the collection
+
+  # @!method stop
+  #   Send the +STOP+ command to every item in the collection
+
+  # @!method move
+  #   Send the +MOVE+ command to every item in the collection
+
+  # @!method increase
+  #   Send the +INCREASE+ command to every item in the collection
+
+  # @!method decrease
+  #   Send the +DECREASE+ command to every item in the collection
+
+  # @!method play
+  #   Send the +PLAY+ command to every item in the collection
+
+  # @!method pause
+  #   Send the +pause+ command to every item in the collection
+
+  # @!method rewind
+  #   Send the +REWIND+ command to every item in the collection
+
+  # @!method fast_forward
+  #   Send the +FAST_FORWARD+ command to every item in the collection
+
+  # @!method next
+  #   Send the +NEXT+ command to every item in the collection
+
+  # @!method previous
+  #   Send the +PREVIOUS+ command to every item in the collection
+
+  # @!visibility private
+  # can't use `include`, because Enumerable has already been included
+  # in other classes
+  def ensure
+    OpenHAB::DSL::Ensure::GenericItemDelegate.new(self)
+  end
+end

data/lib/openhab/dsl/items/semantics.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative 'semantics/enumerable'
+
+module OpenHAB
+  module DSL
+    # Module for implementing semantics helper methods on [GenericItem]
+    #
+    # Wraps https://www.openhab.org/javadoc/latest/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).
+    #
+    # See https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.semantics/model/SemanticTags.csv
+    module Semantics
+      # @!visibility private
+      # import the actual semantics action
+      SemanticsAction = org.openhab.core.model.script.actions.Semantics
+      private_constant :SemanticsAction
+
+      # import all the semantics constants
+      [org.openhab.core.semantics.model.point.Points,
+       org.openhab.core.semantics.model.property.Properties,
+       org.openhab.core.semantics.model.equipment.Equipments,
+       org.openhab.core.semantics.model.location.Locations].each do |parent_tag|
+        parent_tag.stream.for_each do |tag|
+          const_set(tag.simple_name.to_sym, tag.ruby_class)
+        end
+      end
+
+      # put ourself into the global namespace, replacing the action
+      ::Semantics = self # rubocop:disable Naming/ConstantName
+
+      # 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.
+      #
+      # @return [true, false]
+      def location?
+        SemanticsAction.location?(self)
+      end
+
+      # 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.
+      #
+      # @return [true, false]
+      def equipment?
+        SemanticsAction.equipment?(self)
+      end
+
+      # 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.
+      #
+      # @return [true, false]
+      def point?
+        SemanticsAction.point?(self)
+      end
+
+      # Checks if this Item has any semantic tags
+      # @return [true, false]
+      def semantic?
+        !!semantic_type
+      end
+
+      # Gets the related Location Item of this Item.
+      #
+      # Returns +self+ if this Item is a Location. Otherwise, checks ancestor
+      # groups one level at a time, returning the first Location Item found.
+      #
+      # @return [GenericItem, nil]
+      def location
+        SemanticsAction.get_location(self)
+      end
+
+      # Returns the sub-class of [Location] related to this Item.
+      #
+      # In other words, the semantic_type of this Item's Location.
+      #
+      # @return [Class]
+      def location_type
+        SemanticsAction.get_location_type(self)&.ruby_class
+      end
+
+      # Gets the related Equipment Item of this Item.
+      #
+      # Returns +self+ if this Item is an Equipment. Otherwise, checks ancestor
+      # groups one level at a time, returning the first Equipment Item found.
+      #
+      # @return [GenericItem, nil]
+      def equipment
+        SemanticsAction.get_equipment(self)
+      end
+
+      # Returns the sub-class of [Equipment] related to this Item.
+      #
+      # In other words, the semantic_type of this Item's Equipment.
+      #
+      # @return [Class]
+      def equipment_type
+        SemanticsAction.get_equipment_type(self)&.ruby_class
+      end
+
+      # Returns the sub-class of [Point] this Item is tagged with.
+      #
+      # @return [Class]
+      def point_type
+        SemanticsAction.get_point_type(self)&.ruby_class
+      end
+
+      # Returns the sub-class of [Property] this Item is tagged with.
+      # @return [Class]
+      def property_type
+        SemanticsAction.get_property_type(self)&.ruby_class
+      end
+
+      # Returns the sub-class of [Tag] this Item is tagged with.
+      #
+      # It will only return the first applicable Tag, preferring
+      # a sub-class of [Location], [Equipment], or [Point] first,
+      # and if none of those are found, looks for a [Property].
+      # @return [Class]
+      def semantic_type
+        SemanticsAction.get_semantic_type(self)&.ruby_class
+      end
+
+      # 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).
+      #
+      # @example Get all points for a TV
+      #   eGreatTV.points
+      # @example Search an Equipment item for its switch
+      #   eGuestFan.points(Semantics::Switch) # => [GuestFan_Dimmer]
+      # @example Search a Thermostat item for its current temperature item
+      #   eFamilyThermostat.points(Semantics::Status, Semantics::Temperature)
+      #   # => [FamilyThermostat_AmbTemp]
+      # @example Search a Thermostat item for is setpoints
+      #   eFamilyThermostat.points(Semantics::Control, Semantics::Temperature)
+      #   # => [FamilyThermostat_HeatingSetpoint, FamilyThermostat_CoolingSetpoint]
+      # @example Given a A/V receiver's input item, search for its power item
+      #   FamilyReceiver_Input.points(Semantics::Switch) # => [FamilyReceiver_Switch]
+      #
+      # @param [Class] point_or_property_types
+      #   Pass 1 or 2 classes that are sub-classes of [Point] or [Property].
+      #   Note that when comparing against semantic tags, it does a sub-class check.
+      #   So if you search for [Control], you'll get items tagged with [Switch].
+      # @return [Array<GenericItem>]
+      def points(*point_or_property_types)
+        # automatically search the parent equipment (or location?!) for sibling points
+        unless equipment? || location?
+          result = (equipment || location)&.points(*point_or_property_types) || []
+          # remove self. but avoid state comparisons
+          result.delete_if { |item| item.eql?(self) }
+          return result
+        end
+
+        members.points(*point_or_property_types)
+      end
+    end
+  end
+end
+
+# Additions to Enumerable to allow easily filtering groups of items based on the semantic model
+module Enumerable
+  # Returns a new array of items that are a semantics Location (optionally of the given type)
+  def sublocations(type = nil)
+    raise ArgumentError, 'type must be a subclass of Location' if type && !(type < OpenHAB::DSL::Semantics::Location)
+
+    result = select(&:location?)
+    result.select! { |i| i.location_type <= type } if type
+
+    result
+  end
+
+  # Returns a new array of items that are a semantics equipment (optionally of the given type)
+  #
+  # @example Get all TVs in a room
+  #   lGreatRoom.equipments(Semantics::Screen)
+  def equipments(type = nil)
+    raise ArgumentError, 'type must be a subclass of Equipment' if type && !(type < OpenHAB::DSL::Semantics::Equipment)
+
+    result = select(&:equipment?)
+    result.select! { |i| i.equipment_type <= type } if type
+
+    result
+  end
+
+  # Returns a new array of items that are semantics points (optionally of a given type)
+  #
+  # @example Get all the power switch items for every equipment in a room
+  #   lGreatRoom.equipments.points(Semantics::Switch)
+  def points(*point_or_property_types) # rubocop:disable Metrics
+    unless (0..2).cover?(point_or_property_types.length)
+      raise ArgumentError, "wrong number of arguments (given #{point_or_property_types.length}, expected 0..2)"
+    end
+    unless point_or_property_types.all? do |tag|
+             tag < OpenHAB::DSL::Semantics::Point || tag < OpenHAB::DSL::Semantics::Property
+           end
+      raise ArgumentError, 'point_or_property_types must all be a subclass of Point or Property'
+    end
+    if point_or_property_types.count { |tag| tag < OpenHAB::DSL::Semantics::Point } > 1 ||
+       point_or_property_types.count { |tag| tag < OpenHAB::DSL::Semantics::Property } > 1
+      raise ArgumentError, 'point_or_property_types cannot both be a subclass of Point or Property'
+    end
+
+    filter_with_members(&:point?)
+      .select do |point|
+      point_or_property_types.all? do |tag|
+        (tag < OpenHAB::DSL::Semantics::Point && point.point_type&.<=(tag)) ||
+          (tag < OpenHAB::DSL::Semantics::Property && point.property_type&.<=(tag))
+      end
+    end
+  end
+
+  #
+  # Select the elements where the given block returns true.
+  # If the block returns false but the element is a GroupItem with members,
+  # merge its members into the result and filter them using the same block
+  #
+  # @param [Block] &block A block that returns true for the elements and members to be included in the result
+  #
+  # @return [Array] The resulting array
+  #
+  # !@visibility private
+  def filter_with_members(&block)
+    selected, others = partition(&block)
+    others.members.select(&block).concat(selected)
+  end
+end

data/lib/openhab/version.rb

@@ -5,5 +5,5 @@
 #
 module OpenHAB
   # @return [String] Version of OpenHAB helper libraries
-  VERSION = '4.37.0'
+  VERSION = '4.39.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 4.37.0
+  version: 4.39.0
 platform: ruby
 authors:
 - Brian O'Connell
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-08 00:00:00.000000000 Z
+date: 2022-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,6 +80,8 @@ files:
 - lib/openhab/dsl/items/persistence.rb
 - lib/openhab/dsl/items/player_item.rb
 - lib/openhab/dsl/items/rollershutter_item.rb
+- lib/openhab/dsl/items/semantics.rb
+- lib/openhab/dsl/items/semantics/enumerable.rb
 - lib/openhab/dsl/items/string_item.rb
 - lib/openhab/dsl/items/switch_item.rb
 - lib/openhab/dsl/items/timed_command.rb