openhab-scripting 4.39.1 → 4.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ec5b89b1270a09daed465179e9643c559c51491d030f5b6b53431f942d026fb
-  data.tar.gz: 292889a440bfc0f08d091fe5eb31894ca78654cabd5d9684d8b803d2840dd75d
+  metadata.gz: 62974273127c66d888a44c8871b287dd6cfc90485ad04e9d461b407d19474eb1
+  data.tar.gz: d9540eeb7d3df3df1075ff8c79a4bc8eef1ca9e6920860bce2c5a3c64a2931b8
 SHA512:
-  metadata.gz: 30e263e6eec5bf3f0258b198817d68f5ca6d31fbca7bb7ac0187601cbd07a91122daa52991e61615003db5a6e308574136d1b1045ad288329539be3e30b0ff28
-  data.tar.gz: 0e00529a2b6cc75a4e33a44d97623abf2144e38e637d7a3d70bd6a68f8acd19cf7de18811d8306ee9e35effd3756ae4eb53c032106e68d47e122231bb9cc590f
+  metadata.gz: 26fbfcddca4f673fbaf1a2399bb126c06715dfbe966ae1c0a77259bdc5b1debafbbdb9b9103c81d0c8bc31311118b44517504e749611cb0c80cc4ddea1e69e23
+  data.tar.gz: 80e903ea1be4ce311c3f5093fa678bd38a22ddc5e97ac24245faaa5ad14cd5cd383b3e82f9cce11da6d7e062608ce5181a8eed3005f5aab09982f0a78f5eb944

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

@@ -9,9 +9,12 @@ module OpenHAB
         #
         # Comparison
         #
-        # @param [GenericItem, Types::Type, Object] other object to
+        # @param [GenericItem, Types::Type, Object, GenericItemObject] other object to
         #   compare to
         #
+        #   When comparing GenericItemObject on either side, perform object comparison
+        #   return 0 if the object is equal, or nil otherwise.
+        #
         #   If this item is +NULL+ or +UNDEF+, and +other+ is nil, they are
         #   considered equal
         #
@@ -28,21 +31,30 @@ module OpenHAB
         #
         def <=>(other)
           logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
-          # if we're NULL or UNDEF, implement special logic
-          unless state?
-            # if comparing to nil, consider ourselves equal
-            return 0 if other.nil?
-            # if the other object is an Item, only consider equal if we're
-            # in the same _kind_ of UnDefType state
-            return raw_state == other.raw_state if other.is_a?(GenericItem) && !other.state?
 
-            # otherwise, it's a non-nil thing comparing to nil, which is undefined
-            return nil
+          if is_a?(OpenHAB::DSL::GenericItemObject) || other.is_a?(OpenHAB::DSL::GenericItemObject)
+            return eql?(other) ? 0 : nil
           end
 
+          # if we're NULL or UNDEF, implement special logic
+          return nil_comparison unless state?
+
           # delegate to how the state compares to the other object
           state <=> other
         end
+
+        # Special logic for NULL/UNDEF state comparison
+        # @!visibility private
+        def nil_comparison
+          # if comparing to nil, consider ourselves equal
+          return 0 if other.nil?
+          # if the other object is an Item, only consider equal if we're
+          # in the same _kind_ of UnDefType state
+          return raw_state == other.raw_state if other.is_a?(GenericItem) && !other.state?
+
+          # otherwise, it's a non-nil thing comparing to nil, which is undefined
+          nil
+        end
       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/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/persistence.rb

@@ -6,10 +6,13 @@ module OpenHAB
       #
       # Persistence extension for Items
       #
+      # @note Methods that accept a timestamp can accept a ++ZonedDateTime++, Ruby ++Time++, or a ++Duration++.
+      #       When given a positive Duration, the timestamp will be calculated as ++now-Duration++
+      #
       module Persistence
         java_import Java::OrgOpenhabCoreTypesUtil::UnitUtils
 
-        # A wrapper for OpenHAB's HistoricItem that returns the state directly
+        # A state class with an added timestamp attribute. This is used to hold OpenHAB's HistoricItem.
         class HistoricState < SimpleDelegator
           attr_reader :timestamp, :state
 
@@ -29,14 +32,169 @@ module OpenHAB
 
         # All persistence methods that require a timestamp
         PERSISTENCE_METHODS = (QUANTITY_METHODS +
-                              %i[changed_since
+                              %i[changed_since?
                                  evolution_rate
                                  historic_state
                                  maximum_since
                                  minimum_since
-                                 updated_since]).freeze
+                                 updated_since?]).freeze
         private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
 
+        # @!method persist(service = nil)
+        #   Persist the state of the item
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [void]
+
+        # @!method last_update(service = nil)
+        #   Return the time the item was last updated.
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [ZonedDateTime] The timestamp of the last update
+
+        # @!method average_since(timestamp, service = nil)
+        #   Return the average value of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The average value since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method average_between(start, finish, service = nil)
+        #   Return the average value of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The average value between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method delta_since(timestamp, service = nil)
+        #   Return the difference value of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The difference value since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method delta_between(start, finish, service = nil)
+        #   Return the difference value of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The difference value between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method deviation_since(timestamp, service = nil)
+        #   Return the standard deviation of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The standard deviation since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method deviation_between(start, finish, service = nil)
+        #   Return the standard deviation of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The standard deviation between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method sum_since(timestamp, service = nil)
+        #   Return the sum of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The sum since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method sum_between(start, finish, service = nil)
+        #   Return the sum of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The sum between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method variance_since(timestamp, service = nil)
+        #   Return the variance of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The variance since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method variance_between(start, finish, service = nil)
+        #   Return the variance of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The variance between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method changed_since?(timestamp, service = nil)
+        #   Whether the item's state has changed since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Boolean] True if the item's state has changed since the given ++timestamp++, False otherwise.
+
+        # @!method changed_between?(start, finish, service = nil)
+        #   Whether the item's state changed between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Boolean] True if the item's state changed between ++start++ and ++finish++, False otherwise.
+
+        # @!method evolution_rate(timestamp, service = nil)
+        #   Return the evolution rate of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [DecimalType, QuantityType, nil] The evolution rate since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method historic_state(timestamp, service = nil)
+        #   Return the the item's state at the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time at which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The item's state at ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method maximum_since(timestamp, service = nil)
+        #   Return the maximum value of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The maximum value since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method maximum_between(start, finish, service = nil)
+        #   Return the maximum value of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The maximum value between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method minimum_since(timestamp, service = nil)
+        #   Return the minimum value of the item's state since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The minimum value since ++timestamp++,
+        #     or nil if no previous state could be found.
+
+        # @!method minimum_between(start, finish, service = nil)
+        #   Return the minimum value of the item's state between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [HistoricState, nil] The minimum value between ++start++ and ++finish++,
+        #     or nil if no previous state could be found.
+
+        # @!method updated_since?(timestamp, service = nil)
+        #   Whether the item's state has been updated since the given time
+        #   @param [ZonedDateTime, Time, Duration] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Boolean] True if the item's state has been updated since the given ++timestamp++, False otherwise.
+
+        # @!method updated_between?(start, finish, service = nil)
+        #   Whether the item's state was updated between two points in time
+        #   @param [ZonedDateTime, Time, Duration] start The point in time from which to search
+        #   @param [ZonedDateTime, Time, Duration] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @return [Boolean] True if the item's state was updated between ++start++ and ++finish++, False otherwise.
+
         %i[persist last_update].each do |method|
           define_method(method) do |service = nil|
             service ||= persistence_service
@@ -51,7 +209,7 @@ module OpenHAB
         #        searches the first state not equal the current state
         # @param service [String] the name of the PersistenceService to use
         #
-        # @return the previous state or nil if no previous state could be found,
+        # @return [HistoricState, nil] the previous state or nil if no previous state could be found,
         #         or if the default persistence service is not configured or
         #         does not refer to a valid service
         #
@@ -62,17 +220,29 @@ module OpenHAB
         end
 
         PERSISTENCE_METHODS.each do |method|
+          public_method = method.to_s.delete_suffix('?') # For some reason, the boolean methods with '?' are missing
           define_method(method) do |timestamp, service = nil|
             service ||= persistence_service
-            result = PersistenceExtensions.public_send(method, self, to_zdt(timestamp), service&.to_s)
-            if result.is_a? Java::OrgOpenhabCorePersistence::HistoricItem
-              return HistoricState.new(quantify(result.state), result.timestamp)
-            end
+            result = PersistenceExtensions.public_send(public_method, self, to_zdt(timestamp), service&.to_s)
+            wrap_result(result, method)
+          end
+
+          next unless /_since\??$/.match?(method.to_s)
 
-            QUANTITY_METHODS.include?(method) ? quantify(result) : result
+          between_method = method.to_s.sub('_since', '_between').to_sym
+          define_method(between_method) do |start, finish, service = nil|
+            service ||= persistence_service
+            result = PersistenceExtensions.public_send(public_method, self, to_zdt(start), to_zdt(finish),
+                                                       service&.to_s)
+            wrap_result(result, method)
           end
         end
 
+        alias changed_since changed_since?
+        alias changed_between changed_between?
+        alias updated_since updated_since?
+        alias updated_between updated_between?
+
         private
 
         #
@@ -103,6 +273,26 @@ module OpenHAB
           end
         end
 
+        #
+        # Wrap the result into a more convenient object type depending on the method and result.
+        #
+        # @param [Object] result the raw result type to be wrapped
+        # @param [Symbol] method the name of the called method
+        #
+        # @return [HistoricState] a {HistoricState} object if the result was a HistoricItem
+        # @return [QuantityType] a ++QuantityType++ object if the result was an average, delta, deviation,
+        #                        sum, or variance.
+        # @return [Object] the original result object otherwise.
+        #
+        def wrap_result(result, method)
+          java_import org.openhab.core.persistence.HistoricItem
+
+          return HistoricState.new(quantify(result.state), result.timestamp) if result.is_a?(HistoricItem)
+          return quantify(result) if QUANTITY_METHODS.include?(method)
+
+          result
+        end
+
         #
         # Get the specified persistence service from the current thread local variable
         #

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

@@ -73,8 +73,7 @@ module OpenHAB
 
         # 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.
+        # Checks ancestor groups one level at a time, returning the first Location Item found.
         #
         # @return [GenericItem, nil]
         def location
@@ -92,8 +91,7 @@ module OpenHAB
 
         # 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.
+        # Checks ancestor groups one level at a time, returning the first Equipment Item found.
         #
         # @return [GenericItem, nil]
         def equipment
@@ -173,7 +171,7 @@ 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)
+  def locations(type = nil)
     if type && !(type < OpenHAB::DSL::Items::Semantics::Location)
       raise ArgumentError, 'type must be a subclass of Location'
     end
@@ -183,6 +181,8 @@ module Enumerable
 
     result
   end
+  # @deprecated Please use {#locations}
+  alias sublocations locations
 
   # Returns a new array of items that are a semantics equipment (optionally of the given type)
   #

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/log/logger.rb

@@ -54,7 +54,9 @@ module OpenHAB
         define_method(level) do |msg = nil, &block|
           log(severity: level, msg: msg, &block)
         end
-        define_method("#{level}_enabled?") { @sl4fj_logger.send("is_#{level}_enabled") }
+        define_method("#{level}?") { @sl4fj_logger.send("is_#{level}_enabled") }
+        # @deprecated
+        alias_method "#{level}_enabled?", "#{level}?"
       end
 
       #
@@ -62,7 +64,7 @@ module OpenHAB
       # @param [String] preamble to put at start of log message
       # @param [Hash] kwargs key and values to log
       def state(preamble = 'State:', **kwargs)
-        return unless trace_enabled?
+        return unless trace?
 
         states = kwargs.transform_keys(&:to_s)
                        .transform_keys(&:capitalize)
@@ -82,7 +84,7 @@ module OpenHAB
       # @return [Exception] the exception, potentially with a cleaned backtrace.
       #
       def clean_backtrace(error)
-        return error if debug_enabled?
+        return error if debug?
 
         if error.respond_to? :backtrace_locations
           backtrace = error.backtrace_locations.map(&:to_s).grep_v(INTERNAL_CALL_REGEX)
@@ -122,7 +124,7 @@ module OpenHAB
         raise ArgumentError, "Unknown Severity #{severity}" unless LEVELS.include? severity
 
         # Dynamically check enablement of underlying logger, this expands to "is_<level>_enabled"
-        return unless send("#{severity}_enabled?")
+        return unless send("#{severity}?")
 
         # Process block if no message provided
         msg = yield if msg.nil? && block_given?

data/lib/openhab/version.rb

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

metadata

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