openhab-scripting 4.37.1 → 4.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e405e19fe5977dfbe708699abaf9fe3e0e953d2d16450da5b10879b6e0d3494b
-  data.tar.gz: c1ed131f668cd5e214f56164ff10a3e9938df4aaa5f6a55efde4ba23db164f82
+  metadata.gz: 249167484484abf9fb6c7128e5e697fd4e1d767576ad52b22005ee473d52776e
+  data.tar.gz: 6825c83f1cdd668882c3409c0cc828c69e259e553ba736eb9291a0ec1370c57d
 SHA512:
-  metadata.gz: d970bd8b607aad49f59d0746ba56711dcf34a0c199547b76008e3e7f375b6836d06841c8cbdb86f056c4f58704690950583f20b76ae1e641515ea332f594f710
-  data.tar.gz: 7cbc491b62553a735e02f25f690a1244801fc2eac7d2a179dd1777d608a34752e5b549ecb41b73df6765c83ef717fe40d030414bb41291d1372872acaa89c9bb
+  metadata.gz: 7d8c8f1f4aab62fecedbe0b8e6693f263e3a21c2ddbb188e5f16cffaf59643d1ffc27c71bb1c14cd256f1852ab6187890c4289791d862ef8e6dcfb1e8f06d096
+  data.tar.gz: ed683ceab7adbcdfb6882409f8c52fac4e06b15c23662f108488cc192594f21d13d1614b4e645f9c00dec94739321d931fa2c7cfcb1c78ebc6157882c0cdaff3

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)
@@ -92,6 +99,7 @@ module OpenHAB
     module Items
       GenericItem.prepend(OpenHAB::DSL::Ensure::GenericItem)
       GroupItem::GroupMembers.include(OpenHAB::DSL::Ensure::Ensurable)
+      Enumerable.include(OpenHAB::DSL::Ensure::Ensurable)
     end
   end
 end

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/semantics/enumerable.rb

@@ -0,0 +1,79 @@
+# 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
+
+  # @!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
+end

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

@@ -0,0 +1,226 @@
+# 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 it's 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.flat_map(&:members).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
+
+    select do |point|
+      next unless point.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
+end

data/lib/openhab/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 4.37.1
+  version: 4.38.0
 platform: ruby
 authors:
 - Brian O'Connell
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-09 00:00:00.000000000 Z
+date: 2022-04-15 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