openhab-scripting 5.36.2 → 5.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dca6625d5d2a4ac13a8012df40e3d0a0ebdefced290c5cff076465c6f759757
-  data.tar.gz: 25f336aa6c3cd7c7a0e47f5e237fd19ac73f6f1ea989ff18d911e2a66a22048b
+  metadata.gz: 3c7147931d90e0b4f5c7d16fb324ac46f6ddd579e25c32245c49fc1c4a770120
+  data.tar.gz: 718a8d07104975de5fd75900ba97b743319e8a18ff4076dc811ae7b5b0ffbdc5
 SHA512:
-  metadata.gz: 2df6953fce517e82fda1fc8e3a5098c63af45333c1637639f6488597230d2634c18a666eb4bc3ae1302abb0d19fdd64eb9c256b7bb263b6f7d6852b9bead6600
-  data.tar.gz: bfb62aca10a6a2b3bff00adf94f39d1b30f806fc55cc34f503102d6c2c349ad938c1a8f5c71f17d60164eaeb810141f38ca0120a5357feec9f69af7aa71866e2
+  metadata.gz: '0998824497c882bc59e935f13a28aeda241c0f399428ab90403b817e4b4f664db37d2c2225b9ff356535e3cb2ae478f8b091ab09cfda1d091142ae7b0e6ccc85'
+  data.tar.gz: 72037d1a9d371458716fbc88955858d6a615dfc089878226cbb0109706df7c7a9d77f9ebc9001581a0f379e8785a7f752d060369dacb152bdefb5be9bdcbbc89

data/lib/openhab/core/items/persistence.rb

@@ -111,28 +111,37 @@ module OpenHAB
         # @deprecated Use {PersistedState} instead
         HistoricState = PersistedState
 
-        # @!method average_since(timestamp, service = nil)
+        # @!method average_since(timestamp, service = nil, riemann_type: nil)
         #   Returns the average value of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The average value since `timestamp`,
         #     or nil if no previous states could be found.
+        #   @since openHAB 5.0 riemann_type parameter added
 
-        # @!method average_until(timestamp, service = nil)
+        # @!method average_until(timestamp, service = nil, riemann_type: nil)
         #   Returns the average value of the item's state between now until the given time
         #   @param [#to_zoned_date_time] timestamp The point in time until which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The average value until `timestamp`,
         #     or nil if no future states could be found.
         #   @since openHAB 4.2
+        #   @since openHAB 5.0 riemann_type parameter added
 
-        # @!method average_between(start, finish, service = nil)
+        # @!method average_between(start, finish, service = nil, riemann_type: nil)
         #   Returns the average value of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The average value between `start` and `finish`,
         #     or nil if no states could be found.
+        #   @since openHAB 5.0 riemann_type parameter added
 
         # @!method delta_since(timestamp, service = nil)
         #   Returns the difference value of the item's state since the given time
@@ -157,28 +166,37 @@ module OpenHAB
         #   @return [DecimalType, QuantityType, nil] The difference value between `start` and `finish`,
         #     or nil if no states could be found.
 
-        # @!method deviation_since(timestamp, service = nil)
+        # @!method deviation_since(timestamp, service = nil, riemann_type: nil)
         #   Returns the standard deviation of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The standard deviation since `timestamp`,
         #     or nil if no previous states could be found.
+        #   @since openHAB 5.0 riemann_type parameter added
 
-        # @!method deviation_until(timestamp, service = nil)
+        # @!method deviation_until(timestamp, service = nil, riemann_type: nil)
         #   Returns the standard deviation of the item's state beetween now until the given time
         #   @param [#to_zoned_date_time] timestamp The point in time until which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The standard deviation until `timestamp`,
         #     or nil if no future states could be found.
         #   @since openHAB 4.2
+        #   @since openHAB 5.0 riemann_type parameter added
 
-        # @!method deviation_between(start, finish, service = nil)
+        # @!method deviation_between(start, finish, service = nil, riemann_type: nil)
         #   Returns the standard deviation of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The standard deviation between `start` and `finish`,
         #     or nil if no states could be found.
+        #   @since openHAB 5.0 riemann_type parameter added
 
         # @!method median_since(timestamp, service = nil)
         #   Returns the median of the item's state since the given time
@@ -228,28 +246,37 @@ module OpenHAB
         #   @return [DecimalType, QuantityType, nil] The sum between `start` and `finish`,
         #     or nil if no states could be found.
 
-        # @!method variance_since(timestamp, service = nil)
+        # @!method variance_since(timestamp, service = nil, riemann_type: nil)
         #   Returns the variance of the item's state since the given time
         #   @param [#to_zoned_date_time] timestamp The point in time from which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The variance since `timestamp`,
         #     or nil if no previous states could be found.
+        #   @since openHAB 5.0 riemann_type parameter added
 
-        # @!method variance_until(timestamp, service = nil)
+        # @!method variance_until(timestamp, service = nil, riemann_type: nil)
         #   Returns the variance of the item's state between now until the given time
         #   @param [#to_zoned_date_time] timestamp The point in time until which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The variance until `timestamp`,
         #     or nil if no future states could be found.
         #   @since openHAB 4.2
+        #   @since openHAB 5.0 riemann_type parameter added
 
-        # @!method variance_between(start, finish, service = nil)
+        # @!method variance_between(start, finish, service = nil, riemann_type: nil)
         #   Returns the variance of the item's state between two points in time
         #   @param [#to_zoned_date_time] start The point in time from which to search
         #   @param [#to_zoned_date_time] finish The point in time to which to search
         #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
         #   @return [DecimalType, QuantityType, nil] The variance between `start` and `finish`,
         #     or nil if no states could be found.
+        #   @since openHAB 5.0 riemann_type parameter added
 
         # @!method changed_since?(timestamp, service = nil)
         #   Whether the item's state has changed since the given time
@@ -461,6 +488,37 @@ module OpenHAB
         #   @return [Array<PersistedState>] An array of {PersistedState} persisted for this item.
         #   @since openHAB 4.0
 
+        # @!method riemann_sum_since(timestamp, service = nil, riemann_type: nil)
+        #   Returns the Riemann sum of the states since a certain point in time.
+        #   @param [#to_zoned_date_time] timestamp The point in time from which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
+        #   @return [DecimalType, QuantityType, nil] The riemann sum since `timestamp`,
+        #     or nil if no previous states could be found.
+        #   @since openHAB 5.0
+
+        # @!method riemann_sum_until(timestamp, service = nil, riemann_type: nil)
+        #   Returns the Riemann sum of the states between now until a certain point in time.
+        #   @param [#to_zoned_date_time] timestamp The point in time until which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
+        #   @return [DecimalType, QuantityType, nil] The riemann sum until `timestamp`,
+        #     or nil if no previous states could be found.
+        #   @since openHAB 5.0
+
+        # @!method riemann_sum_between(start, finish, service = nil, riemann_type: nil)
+        #   Returns the Riemann sum of the states between two points in time.
+        #   @param [#to_zoned_date_time] start The point in time from which to search
+        #   @param [#to_zoned_date_time] finish The point in time to which to search
+        #   @param [Symbol, String] service An optional persistence id instead of the default persistence service.
+        #   @param [:left, :midpoint, :right, :trapezoidal] riemann_type An optional approximation type for Riemann sum.
+        #     If nil, :left is used.
+        #   @return [DecimalType, QuantityType, nil] The riemann sum between `start` and `finish`,
+        #     or nil if no previous states could be found.
+        #   @since openHAB 5.0
+
         # @!method remove_all_states_since(timestamp, service = nil)
         #   Removes persisted data points since a certain point in time.
         #   @param [#to_zoned_date_time] timestamp The point in time from which to remove
@@ -645,76 +703,103 @@ module OpenHAB
 
         class << self
           # @!visibility private
-          def def_persistence_method(method, quantify: false)
+          def def_persistence_method(method, quantify: false, riemann_param: nil)
             method = method.to_s.dup
             suffix = method.delete_suffix!("?") && "?"
+            riemann_arg = nil
+
+            if riemann_param
+              riemann_param = ", riemann_type: nil"
+              # @deprecated OH4.3 remove if guard when dropping OH 4.3
+              if Actions::PersistenceExtensions.const_defined?(:RiemannType)
+                riemann_arg = "to_riemann_type(riemann_type),"
+              end
+            end
 
             class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{method}#{suffix}(timestamp, service = nil)        # def changed_since?(timestamp, service = nil)
-                service ||= persistence_service                       #   service ||= persistence_service
-                result = Actions::PersistenceExtensions.#{method}(    #   result = Actions::PersistenceExtensions.changed_since(
-                  self,                                               #     self,
-                  timestamp.to_zoned_date_time,                       #     timestamp.to_zoned_date_time,
-                  service&.to_s                                       #     service&.to_s
-                )                                                     #   )
-                wrap_result(result, quantify: #{quantify})            #   wrap_result(result, quantify: false)
-              end                                                     # end
+              def #{method}#{suffix}(timestamp, service = nil#{riemann_param}) # def changed_since?(timestamp, service = nil, riemann_type: nil)
+                service ||= persistence_service                                #   service ||= persistence_service
+                result = Actions::PersistenceExtensions.#{method}(             #   result = Actions::PersistenceExtensions.average_since(
+                  self,                                                        #     self,
+                  timestamp.to_zoned_date_time,                                #     timestamp.to_zoned_date_time,
+                  #{riemann_arg}                                               #     to_riemann_type(riemann_type),
+                  service&.to_s                                                #     service&.to_s
+                )                                                              #   )
+                wrap_result(result, quantify: #{quantify})                     #   wrap_result(result, quantify: false)
+              end                                                              # end
             RUBY
           end
 
           # @!visibility private
-          def def_persistence_methods(method, quantify: false)
+          def def_persistence_methods(method, quantify: false, riemann_param: nil)
             method = method.to_s.dup
             suffix = method.delete_suffix!("?") && "?"
+            riemann_arg = nil
 
-            def_persistence_method("#{method}_since#{suffix}", quantify:)
+            def_persistence_method("#{method}_since#{suffix}", quantify:, riemann_param:)
             # @deprecated OH 4.1 remove if guard, keeping the content, when dropping OH 4.1
             if OpenHAB::Core.version >= OpenHAB::Core::V4_2
-              def_persistence_method("#{method}_until#{suffix}", quantify:)
+              def_persistence_method("#{method}_until#{suffix}", quantify:, riemann_param:)
+            end
+
+            if riemann_param
+              riemann_param = ", riemann_type: nil"
+              # @deprecated OH4.3 remove if guard when dropping OH 4.3
+              if Actions::PersistenceExtensions.const_defined?(:RiemannType)
+                riemann_arg = "to_riemann_type(riemann_type),"
+              end
             end
 
             method = "#{method}_between"
             class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{method}#{suffix}(start, finish, service = nil)    # def changed_between?(start, finish, service = nil)
-                service ||= persistence_service                       #   service ||= persistence_service
-                result = Actions::PersistenceExtensions.#{method}(    #   result = Actions::PersistenceExtensions.changed_between?(
-                  self,                                               #     self,
-                  start.to_zoned_date_time,                           #     start.to_zoned_date_time,
-                  finish.to_zoned_date_time,                          #     finish.to_zoned_date_time,
-                  service&.to_s                                       #     service&.to_s
-                )                                                     #   )
-                wrap_result(result, quantify: #{quantify})            #   wrap_result(result, quantify: false)
-              end                                                     # end
+              def #{method}#{suffix}(start, finish, service = nil#{riemann_param}) # def changed_between?(start, finish, service = nil, riemann_type: nil)
+                service ||= persistence_service                                    #   service ||= persistence_service
+                result = Actions::PersistenceExtensions.#{method}(                 #   result = Actions::PersistenceExtensions.average_between(
+                  self,                                                            #     self,
+                  start.to_zoned_date_time,                                        #     start.to_zoned_date_time,
+                  finish.to_zoned_date_time,                                       #     finish.to_zoned_date_time,
+                  #{riemann_arg}                                                   #     to_riemann_type(riemann_type),
+                  service&.to_s                                                    #     service&.to_s
+                )                                                                  #   )
+                wrap_result(result, quantify: #{quantify})                         #   wrap_result(result, quantify: false)
+              end                                                                  # end
             RUBY
           end
         end
 
-        def_persistence_methods(:average, quantify: true)
-        def_persistence_methods(:median, quantify: true) if OpenHAB::Core.version >= OpenHAB::Core::V4_3
-        def_persistence_methods(:delta, quantify: true)
-        def_persistence_methods(:deviation, quantify: true)
-        def_persistence_methods(:sum, quantify: true)
-        def_persistence_methods(:variance, quantify: true)
-
+        # arranged in alphabetical order
+        def_persistence_methods(:average, quantify: true, riemann_param: true)
         def_persistence_methods(:changed?)
         def_persistence_methods(:count)
+
         def_persistence_methods(:count_state_changes)
         alias_method :state_changes_since, :count_state_changes_since
         alias_method :state_changes_until, :count_state_changes_until if OpenHAB::Core.version >= OpenHAB::Core::V4_2
         alias_method :state_changes_between, :count_state_changes_between
 
+        def_persistence_methods(:delta, quantify: true)
+        def_persistence_methods(:deviation, quantify: true, riemann_param: true)
+
         # @deprecated OH 4.2 - this still exists in OH 4.2 but logs a deprecation warning
         def_persistence_method(:historic_state, quantify: true)
 
-        def_persistence_methods(:maximum, quantify: true)
-        def_persistence_methods(:minimum, quantify: true)
-        def_persistence_methods(:updated?)
-
         def_persistence_methods(:get_all_states, quantify: true)
         alias_method :all_states_since, :get_all_states_since
         alias_method :all_states_until, :get_all_states_until if OpenHAB::Core.version >= OpenHAB::Core::V4_2
         alias_method :all_states_between, :get_all_states_between
 
+        def_persistence_methods(:maximum, quantify: true)
+        def_persistence_methods(:minimum, quantify: true)
+        def_persistence_methods(:median, quantify: true) if OpenHAB::Core.version >= OpenHAB::Core::V4_3
+        # @deprecated OH4.3 remove if guard when dropping OH 4.3
+        if Actions::PersistenceExtensions.const_defined?(:RiemannType)
+          # riemann_sum methods were added in OH 5.0 which already quantifies the result in core
+          def_persistence_methods(:riemann_sum, riemann_param: true)
+        end
+        def_persistence_methods(:sum, quantify: true)
+        def_persistence_methods(:updated?)
+        def_persistence_methods(:variance, quantify: true, riemann_param: true)
+
         if OpenHAB::Core.version >= OpenHAB::Core::V4_2
           def_persistence_method(:persisted_state) # already quantified in core
 
@@ -805,6 +890,15 @@ module OpenHAB
         def persistence_service
           Thread.current[:openhab_persistence_service]
         end
+
+        #
+        # Convert a symbol to a RiemannType enum value
+        # @param [Symbol] sym the symbol to convert
+        # @return [RiemannType] the RiemannType enum value, or nil if sym is nil
+        #
+        def to_riemann_type(sym)
+          Actions::PersistenceExtensions::RiemannType.value_of(sym.to_s.upcase) if sym
+        end
       end
     end
   end

data/lib/openhab/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.36.2"
+    VERSION = "5.37.0"
   end
 end

data/lib/openhab/yard/markdown_helper.rb

@@ -45,6 +45,9 @@ module OpenHAB
               if match
                 log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text#{match ? ":" : "."}\n" \
                          "\t#{match[1] ? "..." : ""}#{match[2].delete("\n")}#{match[3] ? "..." : ""}"
+                # Don't strip the link. This is so literals like {RUBY_ENGINE_VERSION} remain as they are,
+                # not stripped to "RUBY_ENGINE_VERSION"
+                next str
               end
             end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.36.2
+  version: 5.37.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -9,7 +9,7 @@ authors:
 - Jimmy Tanagra
 bindir: bin
 cert_chain: []
-date: 2025-03-18 00:00:00.000000000 Z
+date: 2025-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler