openhab-scripting 4.40.0 → 4.42.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aaa16073cb2b4d71edb5e80debef49282a864bad1e057fb307b5cd8b9ca7844
-  data.tar.gz: 641502dca198f6cf42d5a489153f6c04fd3bf70900d4a0873bfb01d686bea6b7
+  metadata.gz: 5e41958655d441761618cb21164c7954bcb05c037023a080d2a70a741637d951
+  data.tar.gz: ee4252bafef8e2a430f98c80bc3277e5c45ef9cd0c06b645f48da848031f0abf
 SHA512:
-  metadata.gz: 978fe9d74ac7bc6481bb59cfb32a5c917f7707933e68d686be6119096f64daf78a49af1c9e4870abaecc0eec234e50314fae8093f1f04d1c38f6e15cdbe89bd9
-  data.tar.gz: b959d2aef01f436f90a56142e4e2c9a4a532de091bd846b97b799a609e16d849d5df2e3de77d91b0a2de588f0da6cf3e6904205b9236538c123484552484565f
+  metadata.gz: c1dcd8ab59e1732eb76acd9c707d4dbd18dcae94d3fd6236d6c53362958b7fd0c977ef001c109f147df596321a99ee7640aceb25f92530f7cb8f59bd7733de9f
+  data.tar.gz: 70d92d8df318f317c42843cf8eaae67b33c9cdb24f119074f7e59e117ec29f53f1594df05e8fd35059a666a600845375048f991c9cc15b35772fb34b35d83a4f

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/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
         #
@@ -64,15 +222,27 @@ module OpenHAB
         PERSISTENCE_METHODS.each do |method|
           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(method.to_s.delete_suffix('?'), 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(between_method.to_s.delete_suffix('?'), 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/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.40.0'
+  VERSION = '4.42.1'
 end

metadata

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