openhab-scripting 4.41.0 → 4.42.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 101fdd6964b1dd5eaefcf5ecaf528ecc01ca12c280440da11ce8646d10fbd67c
-  data.tar.gz: 40bf18765cc29aee28d9ae486cd7c965435f5cbcf8f47867559bb72ccec7f3d9
+  metadata.gz: '08c9201c21983751d80e9c2e4df683c39cef20763a5321fd2f8fdcd355cdb6c5'
+  data.tar.gz: f0b2c25837d2396e70d11ba503920ff443992bd9cf007b18a2003f6857a17929
 SHA512:
-  metadata.gz: 8a8ce171ac466b46f28e5a5abc59cc2de62a20d16210e58fb7ea33b6ee5a6ad0b9399afb40491142d52396cbbee33b5be444f4d5530176b9ac34764f06a4ec5b
-  data.tar.gz: 57171fa39cfc71afaa8d8cb7488e184ea031cf6f8b01a135410a97317399e8a478d6cf9691ba81168d023882c488b07de5f47a921e516a05589bd198731da8b8
+  metadata.gz: bff012a5dc7caf0e06fb9d0f3aede99afc9ad067004390ae606d392c34fe3662b017395fa3c200e759c2023e4801fb775ee097a29f0b90554f721d8fbbf9cf47
+  data.tar.gz: b862f6f69383d86e1a230d2c702c440c0b6dd465ed22ec16ad03a47166bd319004a8f82147eed2da514b301523f99c917c9d93de56f6ea7b9907ab5713f9d61d

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

@@ -37,7 +37,7 @@ module OpenHAB
           end
 
           # if we're NULL or UNDEF, implement special logic
-          return nil_comparison unless state?
+          return nil_comparison(other) unless state?
 
           # delegate to how the state compares to the other object
           state <=> other
@@ -45,9 +45,10 @@ module OpenHAB
 
         # Special logic for NULL/UNDEF state comparison
         # @!visibility private
-        def nil_comparison
+        def nil_comparison(other)
           # 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?

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/rules/rule_config.rb

@@ -8,7 +8,6 @@ require_relative 'guard'
 require_relative 'rule_triggers'
 require 'openhab/core/entity_lookup'
 require 'openhab/dsl/between'
-require 'openhab/dsl/dsl'
 require 'openhab/dsl/timers'
 
 module OpenHAB

data/lib/openhab/dsl/rules/triggers/conditions/proc.rb

@@ -20,9 +20,6 @@ module OpenHAB
           class Proc
             include OpenHAB::Log
 
-            # Proc that doesn't check any fields
-            ANY = Proc.new.freeze
-
             #
             # Converts supplied ranges to procs that check range
             # @param [Array] ranges objects to convert to range proc if they are ranges
@@ -83,6 +80,9 @@ module OpenHAB
               @command = command
             end
 
+            # Proc that doesn't check any fields
+            ANY = Proc.new.freeze # this needs to be defined _after_ initialize so its instance variables are set
+
             #
             # Process rule
             # @param [Hash] inputs inputs from trigger

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.2'
 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.2
 platform: ruby
 authors:
 - Brian O'Connell
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-28 00:00:00.000000000 Z
+date: 2022-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler