openhab-scripting 4.1.4 → 4.5.0

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

@@ -1,323 +1,17 @@
 # frozen_string_literal: true
 
-require 'bigdecimal'
-require 'forwardable'
-require 'java'
-require 'openhab/dsl/types/quantity'
-require 'openhab/dsl/items/item_delegate'
+require 'openhab/dsl/items/numeric_item'
 
 module OpenHAB
   module DSL
     module Items
-      #
-      # Delegation to OpenHAB Number Item
-      #
-      # rubocop: disable Metrics/ClassLength
-      # Disabled because this class has a single responsibility, there does not appear a logical
-      # way of breaking it up into multiple classes
-      class NumberItem < Numeric
-        extend OpenHAB::DSL::Items::ItemDelegate
-        extend OpenHAB::DSL::Items::ItemCommand
+      java_import org.openhab.core.library.items.NumberItem
 
-        def_item_delegator :@number_item
-
-        java_import org.openhab.core.library.types.DecimalType
-        java_import org.openhab.core.library.types.QuantityType
-        java_import org.openhab.core.types.util.UnitUtils
-        java_import org.openhab.core.library.unit.Units
-
-        item_type Java::OrgOpenhabCoreLibraryItems::NumberItem
-
-        #
-        # Create a new NumberItem
-        #
-        # @param [Java::Org::openhab::core::library::items::NumberItem] number_item OpenHAB number item to delegate to
-        #
-        def initialize(number_item)
-          @number_item = number_item
-          item_missing_delegate { @number_item }
-          super()
-        end
-
-        #
-        # Check if NumberItem is truthy? as per defined by library
-        #
-        # @return [Boolean] True if item is not in state UNDEF or NULL and value is not zero.
-        #
-        def truthy?
-          @number_item.state? && @number_item.state != DecimalType::ZERO
-        end
-
-        #
-        # Coerce objects into a NumberItem
-        #
-        # @param [Object] other object to coerce to a NumberItem if possible
-        #
-        # @return [Object] NumberItem, QuantityTypes, BigDecimal or nil depending on NumberItem configuration
-        #  and/or supplied object
-        #
-        def coerce(other)
-          logger.trace("Coercing #{self} as a request from  #{other.class}")
-          case other
-          when Quantity then coerce_from_quantity(other)
-          when Numeric then  coerce_from_numeric(other)
-          else
-            logger.trace("#{self} cannot be coerced to #{other.class}")
-            nil
-          end
-        end
-
-        #
-        # Compare NumberItem to supplied object
-        #
-        # @param [Object] other object to compare to
-        #
-        # @return [Integer] -1,0,1 or nil depending on value supplied,
-        #   nil comparison to supplied object is not possible.
-        #
-        def <=>(other)
-          logger.trace("NumberItem #{self} <=> #{other} (#{other.class})")
-          case other
-          when NumberItem then number_item_compare(other)
-          when Numeric then numeric_compare(other)
-          when String then string_compare(other)
-          else state_compare(other)
-          end
-        end
-
-        #
-        # Convert NumberItem to a Quantity
-        #
-        # @param [Object] other String or Unit representing an OpenHAB Unit
-        #
-        # @return [OpenHAB::DSL::Types::Quantity] NumberItem converted to supplied Unit
-        #
-        def |(other)
-          other = UnitUtils.parse_unit(other) if other.is_a? String
-
-          if dimension
-            to_qt | other
-          else
-            Quantity.new(QuantityType.new(to_d.to_java, other))
-          end
-        end
-
-        #
-        # Convert NumberItem to a Quantity
-        #
-        # @return [OpenHAB::DSL::Types::Quantity] NumberItem converted to a QuantityUnit
-        #
-        def to_qt
-          if dimension
-            Quantity.new(@number_item.get_state_as(QuantityType))
-          else
-            Quantity.new(QuantityType.new(to_d.to_java, Units::ONE))
-          end
-        end
-
-        #
-        # Converts the NumberItem to an Integer
-        #
-        # @return [Integer] NumberItem as an integer
-        #
-        def to_i
-          to_d&.to_i
-        end
-
-        #
-        # Converts the NumberItem to a float
-        #
-        # @return [Float] NumberItem as a float
-        #
-        def to_f
-          to_d&.to_f
-        end
-
-        #
-        # Converts the NumberItem to a BigDecimal
-        #
-        # @return [BigDecimal] NumberItem as a BigDecimal
-        #
-        def to_d
-          @number_item.state.to_big_decimal.to_d if @number_item.state.respond_to? :to_big_decimal
-        end
-
-        #
-        # Get the Dimension attached to the NumberItem
-        #
-        # @return [Java::org::openhab::core::library::types::QuantityType] dimension
-        #
-        def dimension
-          @number_item.dimension
-        end
-
-        %w[+ - * /].each do |operation|
-          define_method(operation) do |other|
-            logger.trace("Execution math operation '#{operation}' on #{inspect} with #{other.inspect}")
-            left_operand, right_operand = operands_for_operation(other)
-            left_operand.public_send(operation, right_operand)
-          end
-        end
-
-        private
-
-        #
-        # Compare if other responds to state
-        #
-        # @param [Object] other object to compare to
-        #
-        # @return [Integer] -1,0,1 depending on less than, equal to or greater than other
-        #
-        def state_compare(other)
-          other = other.state if other.respond_to? :state
-          @number_item.state <=> other
-        end
-
-        #
-        # Compare if other is a String
-        #
-        # @param [String] other object to compare to
-        #
-        # @return [Integer] -1,0,1,nil depending on less than, equal to or greater than other
-        #   nil if this number item does not have a dimension
-        #
-        def string_compare(other)
-          @number_item.state <=> QuantityType.new(other) if dimension
-        end
-
-        #
-        # Compare if other is a Numeric
-        #
-        # @param [String] other to compare to
-        #
-        # @return [Integer] -1,0,1 depending on less than, equal to or greater than other
-        #
-        def numeric_compare(other)
-          @number_item.state.to_big_decimal.to_d <=> other.to_d
-        end
-
-        #
-        # Get the operands for any operation
-        #
-        # @param [Object] other object to convert to a compatible operand
-        #
-        # @return [Array[Object,Object]] of operands where the first value is the left operand
-        #   and the second value is the right operand
-        #
-        def operands_for_operation(other)
-          case other
-          when NumberItem then number_item_operands(other)
-          when Numeric then [to_d, other.to_d]
-          when String then string_operands(other)
-          else
-            return other.coerce(to_d) if other.respond_to? :coerce
-
-            raise ArgumentError, "#{other.class} can't be coerced into a NumberItem"
-          end
-        end
-
-        #
-        # Get operands for an operation when the right operand is provided as a string
-        #
-        # @param [String] other right operand
-        #
-        # @return [Array[QuantityType,QuantiyType]] of operands where the first value is the left operand
-        #   and the second value is the right operand
-        #
-        def string_operands(other)
-          return [to_qt, Quantity.new(other)] if dimension
-
-          raise ArgumentError, 'Strings are only valid operands if NumberItem is dimensions=ed.'
-        end
-
-        #
-        # Get operands for an operation when the right operand is provided is another number item
-        #
-        # @param [NumberItem] other right operand
-        #
-        # @return [Array<QuantityType,QuantityType>,Array<BigDecimal,BigDecimal>] of operands depending on
-        #   if the left or right operand has a dimensions
-        #
-        def number_item_operands(other)
-          if dimension || other.dimension
-            dimensioned_operands(other)
-          else
-            logger.trace("Both objects lack dimension, self='#{self}' other='#{other}'")
-            # If nothing has a dimension, just use BigDecimals
-            [to_d, other.to_d]
-          end
-        end
-
-        #
-        # Get operands for an operation when the left or right operand has a dimension
-        #
-        # @param [NumberItem] other right operand
-        #
-        # @return [Array<QuantityType,QuantityType>] of operands
-        #
-        def dimensioned_operands(other)
-          logger.trace("Dimensions self='#{dimension}' other='#{other.dimension}'")
-          if dimension
-            if other.dimension
-              # If both numbers have dimensions, do the math on the quantity types.
-              [to_qt, other.to_qt]
-            else
-              # If this number has dimension and the other does not,
-              # do math with this quantity type and the other as a big decimal
-              [to_qt, other]
-            end
-          else
-            # If this number has no dimension and the other does, convert this into a dimensionless quantity
-            [to_qt, other]
-          end
-        end
-
-        #
-        # Compare two number items, taking into account any dimensions
-        #
-        # @param [NumberItem] other number item
-        #
-        # @return [-1,0,1] depending on if other object is less than, equal to or greater than self
-        #
-        def number_item_compare(other)
-          if other.dimension
-            logger.trace('Other is dimensioned, converting self and other to QuantityTypes to compare')
-            to_qt <=> other.to_qt
-          else
-            @number_item.state <=> other.state
-          end
-        end
-
-        #
-        # Coerce from a numberic object depnding on dimension and state
-        #
-        # @param [Numeric] other numeric object to convert
-        #
-        # @return [Array<QuantityType,QuantityType>,Array<BigDecimal,BigDecimal>,nil] depending on
-        #   if this object has a dimension or state
-        #
-        def coerce_from_numeric(other)
-          if dimension
-            [Quantity.new(other), to_qt]
-          elsif @number_item.state?
-            [other.to_d, @number_item.state.to_big_decimal.to_d]
-          end
-        end
-
-        #
-        # Coerce when other is a quantity
-        #
-        # @param [QuantityType] other
-        #
-        # @return [Array<QuanityType,QuantityType] other and self as a quantity type
-        #
-        def coerce_from_quantity(other)
-          as_qt = to_qt
-          logger.trace("Converted #{self} to a Quantity #{as_qt}")
-          [other, as_qt]
-        end
+      # Adds methods to core OpenHAB NumberItem type to make it more natural in
+      # Ruby
+      class NumberItem < GenericItem
+        include NumericItem
       end
     end
   end
 end
-# rubocop: enable Metrics/ClassLength

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'comparable_item'
+require_relative 'item_equality'
+
+module OpenHAB
+  module DSL
+    module Items
+      # Mixin for implementing type coercieon, equality, and arithmetic for
+      # number-like items
+      module NumericItem
+        include Comparable
+        include ComparableItem
+
+        # apply meta-programming methods to including class
+        def self.included(klass)
+          klass.prepend ItemEquality # make sure this is first
+          klass.extend Forwardable
+          klass.delegate %i[+ - * / % | positive? negative? to_d to_f to_i to_int zero?] => :state
+          # remove the JRuby default == so that we can inherit the Ruby method
+          klass.remove_method :==
+        end
+
+        #
+        # Check if NumericItem is truthy? as per defined by library
+        #
+        # @return [Boolean] True if item is not in state +UNDEF+ or +NULL+ and value is not zero.
+        #
+        def truthy?
+          state && !state.zero?
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a NumericType
+        #
+        # @param [Types::NumericType, Numeric] other object to coerce to a
+        #   DateTimeType
+        #
+        # @return [[Types::NumericType, Types::NumericType]]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          return [other, nil] unless state?
+          return [other, state] if other.is_a?(Types::NumericType) || other.respond_to?(:to_d)
+
+          raise TypeError, "can't convert #{other.class} into #{self.class}"
+        end
+
+        # strip trailing zeros from commands
+        # @!visibility private
+        def format_type(command)
+          # DecimalType and PercentType we want to make sure we don't have extra zeros
+          if command.instance_of?(Types::DecimalType) || command.instance_of?(Types::PercentType)
+            return command.to_big_decimal.strip_trailing_zeros.to_plain_string
+          end
+          # BigDecimal types have trailing zeros stripped
+          return command.to_java.strip_trailing_zeros.to_plain_string if command.is_a?(BigDecimal)
+
+          super
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Items
+      #
+      # Persistence extension for Items
+      #
+      module Persistence
+        java_import Java::OrgOpenhabCoreTypesUtil::UnitUtils
+
+        # A wrapper for OpenHAB's HistoricItem that returns the state directly
+        class HistoricState < SimpleDelegator
+          attr_reader :timestamp, :state
+
+          def initialize(state, timestamp)
+            @state = state
+            @timestamp = timestamp
+            super(@state)
+          end
+        end
+
+        # All persistence methods that could return a QuantityType
+        QUANTITY_METHODS = %i[average_since
+                              delta_since
+                              deviation_since
+                              sum_since
+                              variance_since].freeze
+
+        # All persistence methods that require a timestamp
+        PERSISTENCE_METHODS = (QUANTITY_METHODS +
+                              %i[changed_since
+                                 evolution_rate
+                                 historic_state
+                                 maximum_since
+                                 minimum_since
+                                 updated_since]).freeze
+        private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
+
+        %i[persist last_update].each do |method|
+          define_method(method) do |service = nil|
+            service ||= persistence_service
+            PersistenceExtensions.public_send(method, self, service&.to_s)
+          end
+        end
+
+        #
+        # Return the previous state of the item
+        #
+        # @param skip_equal [Boolean] if true, skips equal state values and
+        #        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,
+        #         or if the default persistence service is not configured or
+        #         does not refer to a valid service
+        #
+        def previous_state(service = nil, skip_equal: false)
+          service ||= persistence_service
+          result = PersistenceExtensions.previous_state(self, skip_equal, service&.to_s)
+          HistoricState.new(quantify(result.state), result.timestamp)
+        end
+
+        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
+
+            QUANTITY_METHODS.include?(method) ? quantify(result) : result
+          end
+        end
+
+        private
+
+        #
+        # Convert timestamp to ZonedDateTime if it's a TemporalAmount
+        #
+        # @param [Object] timestamp to convert
+        #
+        # @return [ZonedDateTime]
+        #
+        def to_zdt(timestamp)
+          if timestamp.is_a? Java::JavaTimeTemporal::TemporalAmount
+            logger.trace("Converting #{timestamp} (#{timestamp.class}) to ZonedDateTime")
+            Java::JavaTime::ZonedDateTime.now.minus(timestamp)
+          else
+            timestamp
+          end
+        end
+
+        #
+        # Convert value to QuantityType if it is a DecimalType and a unit is defined
+        #
+        # @param [Object] value The value to convert
+        #
+        # @return [Object] QuantityType or the original value
+        #
+        def quantify(value)
+          if value.is_a?(Types::DecimalType) && state_description&.pattern
+            item_unit = UnitUtils.parse_unit(state_description.pattern)
+            logger.trace("Unitizing #{value} with unit #{item_unit}")
+            Types::QuantityType.new(value.to_big_decimal, item_unit)
+          else
+            value
+          end
+        end
+
+        #
+        # Get the specified persistence service from the current thread local variable
+        #
+        # @return [Object] Persistence service name as String or Symbol, or nil if not set
+        #
+        def persistence_service
+          Thread.current.thread_variable_get(:persistence_service)
+        end
+      end
+    end
+  end
+end

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

@@ -1,48 +1,57 @@
 # frozen_string_literal: true
 
-require 'forwardable'
-require 'java'
-require 'openhab/dsl/items/item_command'
-require 'openhab/dsl/items/item_delegate'
-
 module OpenHAB
   module DSL
     module Items
-      #
-      # Delegator to OpenHAB Player Item
-      #
-      class PlayerItem
-        extend OpenHAB::DSL::Items::ItemCommand
-        extend OpenHAB::DSL::Items::ItemDelegate
-        extend Forwardable
-
-        def_item_delegator :@player_item
-
-        item_type Java::OrgOpenhabCoreLibraryItems::PlayerItem, :play? => :playing?,
-                                                                :pause? => :paused?,
-                                                                :rewind? => :rewinding?,
-                                                                :fastforward? => :fastforwarding?
-
-        # rubocop: disable Style/Alias
-        # Disabled because 'alias' does not work with the dynamically defined methods
-        alias_method :fast_forward, :fastforward
-        alias_method :fast_forwarding?, :fastforwarding?
-        # rubocop: enable Style/Alias
-
-        #
-        # Creates a new PlayerItem
-        #
-        # @param [Java::OrgOpenhabCoreLibraryItems::PlayerItem] player_item
-        #   The OpenHAB PlayerItem to delegate to
-        #
-        def initialize(player_item)
-          logger.trace("Wrapping #{player_item}")
-          @player_item = player_item
-
-          item_missing_delegate { @player_item }
-
-          super()
-        end
+      java_import org.openhab.core.library.items.PlayerItem
+
+      # Adds methods to core OpenHAB NumberItem type to make it more natural in
+      # Ruby
+      class PlayerItem < GenericItem
+        remove_method :==
+
+        # @!method play?
+        #   Check if the item state == +PLAYING+
+        #   @return [Boolean]
+
+        # @deprecated
+        # @!parse alias play? playing?
+
+        # @!method paused?
+        #   Check if the item state == +PAUSED+
+        #   @return [Boolean]
+
+        # @!method rewinding?
+        #   Check if the item state == +REWIND+
+        #   @return [Boolean]
+
+        # @!method fast_forwarding?
+        #   Check if the item state == +FASTFORWARD+
+        #   @return [Boolean]
+
+        # @!method play
+        #   Send the +PLAY+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method pause
+        #   Send the +PAUSE+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method rewind
+        #   Send the +REWIND+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method fast_forward
+        #   Send the +FASTFORWARD+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method next
+        #   Send the +NEXT+ command to the item
+        #   @return [PlayerItem] +self+
+
+        # @!method previous
+        #   Send the +PREVIOUS+ command to the item
+        #   @return [PlayerItem] +self+
       end
     end
   end