openhab-scripting 4.41.0 → 4.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 101fdd6964b1dd5eaefcf5ecaf528ecc01ca12c280440da11ce8646d10fbd67c
-  data.tar.gz: 40bf18765cc29aee28d9ae486cd7c965435f5cbcf8f47867559bb72ccec7f3d9
+  metadata.gz: 62974273127c66d888a44c8871b287dd6cfc90485ad04e9d461b407d19474eb1
+  data.tar.gz: d9540eeb7d3df3df1075ff8c79a4bc8eef1ca9e6920860bce2c5a3c64a2931b8
 SHA512:
-  metadata.gz: 8a8ce171ac466b46f28e5a5abc59cc2de62a20d16210e58fb7ea33b6ee5a6ad0b9399afb40491142d52396cbbee33b5be444f4d5530176b9ac34764f06a4ec5b
-  data.tar.gz: 57171fa39cfc71afaa8d8cb7488e184ea031cf6f8b01a135410a97317399e8a478d6cf9691ba81168d023882c488b07de5f47a921e516a05589bd198731da8b8
+  metadata.gz: 26fbfcddca4f673fbaf1a2399bb126c06715dfbe966ae1c0a77259bdc5b1debafbbdb9b9103c81d0c8bc31311118b44517504e749611cb0c80cc4ddea1e69e23
+  data.tar.gz: 80e903ea1be4ce311c3f5093fa678bd38a22ddc5e97ac24245faaa5ad14cd5cd383b3e82f9cce11da6d7e062608ce5181a8eed3005f5aab09982f0a78f5eb944

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/version.rb

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

metadata

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