openhab-scripting 4.38.0 → 4.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 249167484484abf9fb6c7128e5e697fd4e1d767576ad52b22005ee473d52776e
-  data.tar.gz: 6825c83f1cdd668882c3409c0cc828c69e259e553ba736eb9291a0ec1370c57d
+  metadata.gz: 7aaa16073cb2b4d71edb5e80debef49282a864bad1e057fb307b5cd8b9ca7844
+  data.tar.gz: 641502dca198f6cf42d5a489153f6c04fd3bf70900d4a0873bfb01d686bea6b7
 SHA512:
-  metadata.gz: 7d8c8f1f4aab62fecedbe0b8e6693f263e3a21c2ddbb188e5f16cffaf59643d1ffc27c71bb1c14cd256f1852ab6187890c4289791d862ef8e6dcfb1e8f06d096
-  data.tar.gz: ed683ceab7adbcdfb6882409f8c52fac4e06b15c23662f108488cc192594f21d13d1614b4e645f9c00dec94739321d931fa2c7cfcb1c78ebc6157882c0cdaff3
+  metadata.gz: 978fe9d74ac7bc6481bb59cfb32a5c917f7707933e68d686be6119096f64daf78a49af1c9e4870abaecc0eec234e50314fae8093f1f04d1c38f6e15cdbe89bd9
+  data.tar.gz: b959d2aef01f436f90a56142e4e2c9a4a532de091bd846b97b799a609e16d849d5df2e3de77d91b0a2de588f0da6cf3e6904205b9236538c123484552484565f

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

@@ -99,7 +99,6 @@ 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

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
-require 'openhab/dsl/items/metadata'
-require 'openhab/dsl/items/persistence'
-require 'openhab/dsl/items/semantics'
+require 'delegate'
+require 'forwardable'
+
+require_relative 'metadata'
+require_relative 'persistence'
+require_relative 'semantics'
 
 require_relative 'item_equality'
 
@@ -170,6 +173,17 @@ module OpenHAB
           other.instance_of?(self.class) && hash == other.hash
         end
 
+        #
+        # A method to indicate that item comparison is requested instead of state comparison
+        #
+        # Example: Item1.item == items['Item1'].item should return true
+        #
+        # See ItemEquality#==
+        #
+        def item
+          @item ||= GenericItemObject.new(self)
+        end
+
         # @!method null?
         #   Check if the item state == +NULL+
         #   @return [Boolean]
@@ -201,5 +215,15 @@ module OpenHAB
         end
       end
     end
+
+    # A helper class to flag that item comparison is wanted instead of state comparison
+    # It is used by ItemEquality#===
+    class GenericItemObject < SimpleDelegator
+      extend Forwardable
+      include Log
+      include OpenHAB::DSL::Items::ItemEquality
+
+      def_delegator :__getobj__, :instance_of? # instance_of? is used by GenericItem#eql? to check for item equality
+    end
   end
 end

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

@@ -44,6 +44,7 @@ module OpenHAB
 
         include Enumerable
         include ComparableItem
+        prepend Semantics # make Semantics#points take precedence over Enumerable#points for GroupItem
 
         remove_method :==
 

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

@@ -22,7 +22,8 @@ module OpenHAB
         # @return [Boolean]
         #
         def ==(other)
-          logger.trace("(#{self.class}) #{self} == #{other} (#{other.class})")
+          logger.trace { "ItemEquality#== (#{self.class}) #{self} == #{other} (#{other.class})" }
+          return eql?(other) if generic_item_object?(other)
           return true if equal?(other) || eql?(other)
           return true if !state? && other.nil?
 
@@ -30,6 +31,28 @@ module OpenHAB
 
           state == other
         end
+
+        #
+        # Check item object equality for grep
+        #
+        def ===(other)
+          logger.trace { "ItemEquality#=== (#{self.class}) #{self} == #{other} (#{other.class})" }
+          eql?(other)
+        end
+
+        private
+
+        #
+        # Determines if an object equality check is required, based on whether
+        # either operand is a GenericItemObject
+        #
+        # @param [Object] other
+        #
+        # @return [Boolean]
+        #
+        def generic_item_object?(other)
+          other.is_a?(OpenHAB::DSL::GenericItemObject) || is_a?(OpenHAB::DSL::GenericItemObject)
+        end
       end
     end
   end

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

@@ -32,6 +32,11 @@ module Enumerable
     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
 
@@ -76,4 +81,11 @@ module Enumerable
 
   # @!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

@@ -4,168 +4,167 @@ 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)
+    module Items
+      # 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
-      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
+        # 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 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 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
+        # 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
+        # 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
+        # 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
+        # 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 [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 [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 [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
+        # 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?
+        # 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)
+          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) || []
           # 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
@@ -175,7 +174,9 @@ end
 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)
+    if type && !(type < OpenHAB::DSL::Items::Semantics::Location)
+      raise ArgumentError, 'type must be a subclass of Location'
+    end
 
     result = select(&:location?)
     result.select! { |i| i.location_type <= type } if type
@@ -188,7 +189,9 @@ module Enumerable
   # @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)
+    if type && !(type < OpenHAB::DSL::Items::Semantics::Equipment)
+      raise ArgumentError, 'type must be a subclass of Equipment'
+    end
 
     result = select(&:equipment?)
     result.select! { |i| i.equipment_type <= type } if type
@@ -199,27 +202,25 @@ module Enumerable
   # 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)
+  #   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
+             tag < OpenHAB::DSL::Items::Semantics::Point || tag < OpenHAB::DSL::Items::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
+    if point_or_property_types.count { |tag| tag < OpenHAB::DSL::Items::Semantics::Point } > 1 ||
+       point_or_property_types.count { |tag| tag < OpenHAB::DSL::Items::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))
+      point.point? && point_or_property_types.all? do |tag|
+        (tag < OpenHAB::DSL::Items::Semantics::Point && point.point_type <= tag) ||
+          (tag < OpenHAB::DSL::Items::Semantics::Property && point.property_type&.<=(tag))
       end
     end
   end

data/lib/openhab/dsl/rules/triggers/cron/cron.rb

@@ -35,7 +35,7 @@ module OpenHAB
         #
         # @param [String] expression OpenHAB style cron expression
         # @param [Object] attach object to be attached to the trigger
-        # @param [Hash] elements cron expression elements (second, minute, hour, dom, month, dow, year)
+        # @param [Hash] fields cron expression elements (second, minute, hour, dom, month, dow, year)
         #
         def cron(expression = nil, attach: nil, **fields)
           if fields.any?
@@ -124,7 +124,7 @@ module OpenHAB
           #
           # Create a cron map from a MonthDay
           #
-          # @param [Java::JavaTime::MonthDay] month_day
+          # @param [Java::JavaTime::MonthDay] monthday a {MonthDay} object
           # @param [Object] at TimeOfDay or String representing time of day
           #
           # @return [Hash] map describing cron expression
@@ -152,7 +152,7 @@ module OpenHAB
           #
           # Create a cron map from cron elements
           #
-          # @param [Hash] elements Cron fields (second, minute, hour, dom, month, dow, year)
+          # @param [Hash] fields Cron fields (second, minute, hour, dom, month, dow, year)
           #
           # @return [Hash] map describing cron expression
           #

data/lib/openhab/dsl/states.rb

@@ -33,7 +33,7 @@ module OpenHAB
       # Check if all the given items have a state (not UNDEF or NULL)
       #
       # @param [Array] items whose state must be non-nil
-      # @param [<Type>] check_things when true, also ensures that all linked things are online
+      # @param [<Type>] things when true, also ensures that all linked things are online
       #
       # @return [Boolean] true if all the items have a state, false otherwise
       #
@@ -51,7 +51,7 @@ module OpenHAB
         #
         # Create a StateStorage object that stores the states of the given items
         #
-        # @param [Array<Item>] *items A list of items
+        # @param [Array<Item>] items A list of items
         #
         # @return [StateStorage] A state storage object
         #

data/lib/openhab/dsl/types/point_type.rb

@@ -57,7 +57,7 @@ module OpenHAB
         # @return [Boolean]
         #
         def ==(other) # rubocop:disable Metrics
-          logger.trace("(#{self.class}) #{self} == #{other} (#{other.class})")
+          logger.trace { "(#{self.class}) #{self} == #{other} (#{other.class})" }
           if other.is_a?(Items::LocationItem) ||
              (other.is_a?(Items::GroupItem) && other.base_item.is_a?(LocationItem))
             return false unless other.state?

data/lib/openhab/dsl/types/type.rb

@@ -48,8 +48,8 @@ module OpenHAB
         #                   or item state of the same type
         #
         def ===(other)
-          logger.trace("(#{self.class}) #{self} === #{other} (#{other.class})")
-          other = other.state if other.respond_to?(:state)
+          logger.trace { "Type (#{self.class}) #{self} === #{other} (#{other.class})" }
+          other = other.state if other.respond_to?(:state) && !other.is_a?(OpenHAB::DSL::GenericItemObject)
           return false unless instance_of?(other.class)
 
           eql?(other)
@@ -62,7 +62,7 @@ module OpenHAB
         #   type conversions
         #
         def ==(other) # rubocop:disable Metrics
-          logger.trace("(#{self.class}) #{self} == #{other} (#{other.class})")
+          logger.trace { "(#{self.class}) #{self} == #{other} (#{other.class})" }
           return true if equal?(other)
 
           # i.e. ON == OFF, REFRESH == ON, ON == REFRESH

data/lib/openhab/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 4.38.0
+  version: 4.40.0
 platform: ruby
 authors:
 - Brian O'Connell
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-15 00:00:00.000000000 Z
+date: 2022-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler