openhab-scripting 4.1.4 → 4.5.0

data/lib/openhab/dsl/types/quantity_type.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative 'numeric_type'
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.QuantityType
+
+      # global alias
+      ::QuantityType = QuantityType
+
+      # @deprecated
+      # Backwards-compatible alias
+      Quantity = QuantityType
+
+      # Adds methods to core OpenHAB QuantityType to make it more natural in Ruby
+      class QuantityType # rubocop:disable Metrics/ClassLength
+        # @!parse include Type
+        include NumericType
+
+        # private alias
+        ONE = org.openhab.core.library.unit.Units::ONE
+        private_constant :ONE
+
+        #
+        # Convert this quantity into a another unit
+        #
+        # @param [Object] other String or Unit to convert to
+        #
+        # @return [QuantityType] This quantity converted to another unit
+        #
+        def |(other)
+          other = org.openhab.core.types.util.UnitUtils.parse_unit(other) if other.is_a?(String)
+
+          to_unit(other)
+        end
+
+        #
+        # Comparison
+        #
+        # @param [NumericType, Items::NumericItem, Numeric, String]
+        #   other object to compare to
+        #
+        # @return [Integer, nil] -1, 0, +1 depending on whether +other+ is
+        #   less than, equal to, or greater than self
+        #
+        #   nil is returned if the two values are incomparable
+        #
+        def <=>(other) # rubocop:disable Metrics
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          if other.is_a?(self.class)
+            compare_to(other)
+          elsif other.is_a?(Items::NumericItem) ||
+                (other.is_a?(Items::GroupItem) && other.base_item.is_a?(NumericItem))
+            return nil unless other.state?
+
+            self <=> other.state
+          elsif other.respond_to?(:to_str)
+            compare_to(QuantityType.new(other.to_str))
+          elsif other.respond_to?(:to_d)
+            compare_to(QuantityType.new(other.to_d.to_java, Units.unit || unit))
+          elsif other.respond_to?(:coerce)
+            lhs, rhs = other.coerce(self)
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a QuantityType
+        #
+        # @param [Items::NumericItem, Numeric, Type, String] other object to
+        #   coerce to a {QuantityType}
+        #
+        #   if +other+ is a {Type}, +self+ will instead be coerced
+        #   to that type to accomodate comparison with things such as {OnOffType}
+        #
+        # @return [[QuantityType, QuantityType]]
+        def coerce(other) # rubocop:disable Metrics
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          if other.is_a?(Items::NumericItem) ||
+             (other.is_a?(Items::GroupItem) && other.base_item.is_a?(Items::NumericItem))
+            raise TypeError, "can't convert #{UnDefType} into #{self.class}" unless other.state?
+
+            [other.state, self]
+          elsif other.is_a?(Type)
+            [other, as(other.class)]
+          elsif other.respond_to?(:to_d)
+            [QuantityType.new(other.to_d.to_java, ONE), self]
+          elsif other.is_a?(String)
+            [QuantityType.new(other), self]
+          else
+            raise TypeError, "can't convert #{other.class} into #{self.class}"
+          end
+        end
+
+        # arithmetic operators
+        alias -@ negate
+
+        {
+          :add => :+,
+          :subtract => :-
+        }.each do |java_op, ruby_op|
+          convert = 'self.class.new(other, Units.unit || unit)'
+
+          class_eval( # rubocop:disable Style/DocumentDynamicEvalDefinition https://github.com/rubocop/rubocop/issues/10179
+            # def +(other)
+            #   logger.trace("#{self} + #{other} (#{other.class})")
+            #   if other.is_a?(Items::NumericItem) ||
+            #     (other.is_a?(Items::GroupItem) && other.base_item.is_a?(Items::NumericItem))
+            #     self + other.state
+            #   elsif other.is_a?(QuantityType)
+            #     add_quantity(other)
+            #   elsif other.is_a?(DecimalType)
+            #     other = other.to_big_decimal
+            #     add_quantity(self.class.new(other, Units.unit || unit))
+            #   elsif other.is_a?(java.math.BigDecimal)
+            #     add_quantity(self.class.new(other, Units.unit || unit))
+            #   elsif other.respond_to?(:to_str)
+            #     self + self.class.new(other)
+            #   elsif other.respond_to?(:to_d)
+            #     other = other.to_d.to_java
+            #     add_quantity(self.class.new(other, Units.unit || unit))
+            #   elsif other.respond_to?(:coerce)
+            #     lhs, rhs = other.coerce(to_d)
+            #     lhs = rhs
+            #   else
+            #     raise TypeError, "#{other.class} can't be coerced into #{self.class}"
+            #   end
+            # end
+            <<~RUBY, __FILE__, __LINE__ + 1
+              def #{ruby_op}(other)
+                logger.trace("\#{self} #{ruby_op} \#{other} (\#{other.class})")
+                if other.is_a?(Items::NumericItem) ||
+                  (other.is_a?(Items::GroupItem) && other.base_item.is_a?(Items::NumericItem))
+                  self #{ruby_op} other.state
+                elsif other.is_a?(QuantityType)
+                  #{java_op}_quantity(other)
+                elsif other.is_a?(DecimalType)
+                  other = other.to_big_decimal
+                  #{java_op}_quantity(#{convert})
+                elsif other.is_a?(java.math.BigDecimal)
+                  #{java_op}_quantity(#{convert})
+                elsif other.respond_to?(:to_str)
+                  self #{ruby_op} self.class.new(other)
+                elsif other.respond_to?(:to_d)
+                  other = other.to_d.to_java
+                  #{java_op}_quantity(#{convert})
+                elsif other.respond_to?(:coerce)
+                  lhs, rhs = other.coerce(to_d)
+                  lhs #{ruby_op} rhs
+                else
+                  raise TypeError, "\#{other.class} can't be coerced into \#{self.class}"
+                end
+              end
+            RUBY
+          )
+        end
+
+        {
+          :multiply => :*,
+          :divide => :/
+        }.each do |java_op, ruby_op|
+          class_eval( # rubocop:disable Style/DocumentDynamicEvalDefinition https://github.com/rubocop/rubocop/issues/10179
+            # def *(other)
+            #   logger.trace("#{self} * #{other} (#{other.class})")
+            #   if other.is_a?(Items::NumericItem) ||
+            #       (other.is_a?(Items::GroupItem) && other.base_item.is_a?(Items::NumericItem))
+            #     self * other.state
+            #   elsif other.is_a?(QuantityType)
+            #     multiply_quantity(other)
+            #   elsif other.is_a?(DecimalType)
+            #     multiply(other.to_big_decimal)
+            #   elsif other.is_a?(java.math.BigDecimal)
+            #     multiply(other)
+            #   elsif other.respond_to?(:to_str)
+            #     self * self.class.new(other)
+            #   elsif other.respond_to?(:to_d)
+            #     multiply(other.to_d.to_java)
+            #   elsif other.respond_to?(:coerce)
+            #     lhs, rhs = other.coerce(to_d)
+            #     lhs * rhs
+            #   else
+            #     raise TypeError, "#{other.class} can't be coerced into #{self.class}"
+            #   end
+            # end
+            <<~RUBY, __FILE__, __LINE__ + 1
+              def #{ruby_op}(other)
+                logger.trace("\#{self} #{ruby_op} \#{other} (\#{other.class})")
+                if other.is_a?(Items::NumericItem) ||
+                   (other.is_a?(Items::GroupItem) && other.base_item.is_a?(Items::NumericItem))
+                  self #{ruby_op} other.state
+                elsif other.is_a?(QuantityType)
+                  #{java_op}_quantity(other)
+                elsif other.is_a?(DecimalType)
+                  #{java_op}(other.to_big_decimal)
+                elsif other.is_a?(java.math.BigDecimal)
+                  #{java_op}(other)
+                elsif other.respond_to?(:to_str)
+                  self #{ruby_op} self.class.new(other)
+                elsif other.respond_to?(:to_d)
+                  #{java_op}(other.to_d.to_java)
+                elsif other.respond_to?(:coerce)
+                  lhs, rhs = other.coerce(to_d)
+                  lhs #{ruby_op} rhs
+                else
+                  raise TypeError, "\#{other.class} can't be coerced into \#{self.class}"
+                end
+              end
+            RUBY
+          )
+        end
+
+        # if it's a dimensionless quantity, change the unit to match other_unit
+        # @!visibility private
+        def unitize(other_unit = unit)
+          # prefer converting to the thread-specified unit if there is one
+          other_unit = Units.unit || other_unit
+          logger.trace("Converting #{self} to #{other_unit}")
+
+          case unit
+          when ONE
+            QuantityType.new(to_big_decimal, other_unit)
+          when other_unit
+            self
+          else
+            to_unit(other_unit)
+          end
+        end
+
+        # if unit is +ONE+, return a plain Java BigDecimal
+        # @!visibility private
+        def deunitize
+          return to_big_decimal if unit == ONE
+
+          self
+        end
+
+        private
+
+        # do addition directly against a QuantityType while ensuring we unitize
+        # both sides
+        def add_quantity(other)
+          unitize(other.unit).add(other.unitize(unit))
+        end
+
+        # do subtraction directly against a QuantityType while ensuring we
+        # unitize both sides
+        def subtract_quantity(other)
+          unitize(other.unit).subtract(other.unitize(unit))
+        end
+
+        # do multiplication directly against a QuantityType while ensuring
+        # we deunitize both sides, and also invert the operation if one side
+        # isn't actually a unit
+        def multiply_quantity(other)
+          lhs = deunitize
+          rhs = other.deunitize
+          # reverse the arguments if it's multiplication and the LHS isn't a QuantityType
+          lhs, rhs = rhs, lhs if lhs.is_a?(java.math.BigDecimal)
+          # what a waste... using a QuantityType to multiply two dimensionless quantities
+          # have to make sure lhs is still a QuantityType in order to return a new
+          # QuantityType that's still dimensionless
+          lhs = other if lhs.is_a?(java.math.BigDecimal)
+
+          lhs.multiply(rhs)
+        end
+
+        alias divide_quantity divide
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/refresh_type.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.types.RefreshType
+
+      # Adds methods to core OpenHAB RefreshType to make it more natural in Ruby
+      class RefreshType # rubocop:disable Lint/EmptyClass
+        # @!parse include Type
+
+        # @!method refresh?
+        #   Check if == +REFRESH+
+        #   @return [Boolean]
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/rewind_fastforward_type.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.RewindFastforwardType
+
+      # Adds methods to core OpenHAB RewindFastforwardType to make it more
+      # natural in Ruby
+      class RewindFastforwardType # rubocop:disable Lint/EmptyClass
+        # @!parse include Type
+
+        # @!method rewinding?
+        #   Check if == +REWIND+
+        #   @return [Boolean]
+
+        # @!parse alias rewind? rewinding?
+
+        # @!method fast_forwarding?
+        #   Check if == +FASTFORWARD+
+        #   @return [Boolean]
+
+        # @!parse alias fast_forward? fast_forwarding?
+
+        # @deprecated
+        # @!parse alias fastforward? fast_forwarding?
+
+        # @deprecated
+        # @!parse alias fastforwarding? fast_forwarding?
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/stop_move_type.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.StopMoveType
+
+      # Adds methods to core OpenHAB StopMoveType to make it more
+      # natural in Ruby
+      class StopMoveType # rubocop:disable Lint/EmptyClass
+        # @!parse include Type
+
+        # @!method stop?
+        #   Check if == +STOP+
+        #   @return [Boolean]
+
+        # @!method move?
+        #   Check if == +MOVE+
+        #   @return [Boolean]
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/string_type.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'comparable_type'
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.StringType
+
+      #
+      # Add methods to core OpenHAB StringType to make it behave as a Ruby
+      # String object
+      #
+      class StringType
+        # @!parse include Type
+
+        extend Forwardable
+        include Comparable
+        include ComparableType
+
+        #
+        # Check equality without type conversion
+        #
+        # @return [Boolean] if the same value is represented, without type
+        #   conversion
+        def eql?(other)
+          return false unless other.instance_of?(self.class)
+
+          to_s.compare_to(other.to_s).zero?
+        end
+
+        #
+        # Comparison
+        #
+        # @param [StringType, Items::StringItem, String]
+        #   other object to compare to
+        #
+        # @return [Integer, nil] -1, 0, +1 depending on whether +other+ is
+        #   less than, equal to, or greater than self
+        #
+        #   nil is returned if the two values are incomparable
+        #
+        def <=>(other) # rubocop:disable Metrics
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          if other.is_a?(Items::StringItem) ||
+             (other.is_a?(Items::GroupItem) && other.base_item.is_a?(StringItem))
+            return nil unless other.state?
+
+            self <=> other.state
+          elsif other.respond_to?(:to_str)
+            to_str <=> other.to_str
+          elsif other.respond_to?(:coerce)
+            lhs, rhs = other.coerce(self)
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a StringType
+        #
+        # @param [Items::StringItem, String] other object to coerce to a
+        #   DateTimeType
+        #
+        # @return [[StringType, StringType]]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          if other.is_a?(Items::StringItem)
+            raise TypeError, "can't convert #{other.raw_state} into #{self.class}" unless other.state?
+
+            [other.state, self]
+          elsif other.respond_to?(:to_str)
+            [String.new(other.to_str), self]
+          else
+            raise TypeError, "can't convert #{other.class} into #{self.class}"
+          end
+        end
+
+        # any method that exists on String gets forwarded to to_s
+        delegate (String.instance_methods - instance_methods) => :to_s
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/type.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.types.Type
+
+      #
+      # Add basic type conversion and comparison to all core OpenHAB types
+      #
+      module Type
+        # can't alias because to_s doesn't exist on Type
+        # @!visibility private
+        def inspect
+          to_s
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to the same Type
+        #
+        # @param [Type] other object to coerce to the same
+        #   Type as this one
+        #
+        # @return [[Type, Type]]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} (#{self.class}) as a request from #{other.class}")
+          return [other.as(self.class), self] if other.is_a?(Type)
+
+          raise TypeError, "can't convert #{other.class} into #{self.class}"
+        end
+
+        #
+        # Check equality without type conversion
+        #
+        # @return [Boolean] if the same value is represented, without type
+        #   conversion
+        def eql?(other)
+          return false unless other.instance_of?(self.class)
+
+          equals(other)
+        end
+
+        #
+        # Check equality, including type conversion
+        #
+        # @return [Boolean] if the same value is represented, including
+        #   type conversions
+        #
+        def ==(other)
+          return true if equal?(other)
+
+          # i.e. ON == OFF, REFRESH == ON, ON == REFRESH
+          # (RefreshType isn't really coercible)
+          return equals(other) if other.instance_of?(self.class) || is_a?(RefreshType) || other.is_a?(RefreshType)
+
+          # i.e. ON == DimmerItem (also case statements)
+          return self == other.raw_state if other.is_a?(Items::GenericItem)
+
+          if other.respond_to?(:coerce)
+            lhs, rhs = other.coerce(self)
+            return lhs == rhs
+          end
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/types.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'type'
+
+require_relative 'date_time_type'
+require_relative 'decimal_type'
+require_relative 'hsb_type'
+require_relative 'increase_decrease_type'
+require_relative 'next_previous_type'
+require_relative 'open_closed_type'
+require_relative 'on_off_type'
+require_relative 'percent_type'
+require_relative 'play_pause_type'
+require_relative 'quantity_type'
+require_relative 'refresh_type'
+require_relative 'rewind_fastforward_type'
+require_relative 'stop_move_type'
+require_relative 'string_type'
+require_relative 'up_down_type'
+require_relative 'un_def_type'
+
+module OpenHAB
+  module DSL
+    #
+    # Contains all OpenHAB *Type classes, as well as associated support
+    # modules
+    #
+    module Types
+      # Hash taking a Enum value, and returning two symbols of
+      # predicates to be defined for it. the first is the "command" form,
+      # which should be defined on ItemCommandEvent, and on the Type itself.
+      # the second is "state" form, which should be defined on the applicable
+      # Item, and on the Type itself.
+      # @!visibility private
+      PREDICATE_ALIASES = Hash.new { |_h, k| [:"#{k.downcase}?"] * 2 }
+                              .merge({
+                                       'PLAY' => %i[play? playing?],
+                                       'PAUSE' => %i[pause? paused?],
+                                       'REWIND' => %i[rewind? rewinding?],
+                                       'FASTFORWARD' => %i[fast_forward? fast_forwarding?]
+                                     }).freeze
+
+      # Hash taking a Enum value, and returning an array of symbols
+      # of the command to define for it
+      # @!visibility private
+      COMMAND_ALIASES = Hash.new { |_h, k| k.downcase.to_sym }
+                            .merge({
+                                     'FASTFORWARD' => :fast_forward
+                                   }).freeze
+
+      constants.map { |c| const_get(c) }
+               .grep(Module)
+               .select { |k| k < java.lang.Enum }
+               .each do |klass|
+        # make sure == from Type is inherited
+        klass.remove_method(:==)
+
+        # dynamically define predicate methods
+        klass.values.each do |value| # rubocop:disable Style/HashEachMethods this isn't a Ruby hash
+          # include all the aliases that we define for items both command and
+          # state aliases (since types can be interrogated as an incoming
+          # command, or as the state of an item)
+          command = :"#{COMMAND_ALIASES[value.to_s]}?"
+          states = PREDICATE_ALIASES[value.to_s]
+
+          ([command] | states).each do |method|
+            OpenHAB::Core.logger.trace("Defining #{klass}##{method} for #{value}")
+            klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{method}       # def on?
+                self == #{value}  #   self == ON
+              end                 # end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/un_def_type.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.types.UnDefType
+
+      # Adds methods to core OpenHAB UnDefType to make it more natural in Ruby
+      class UnDefType # rubocop:disable Lint/EmptyClass
+        # @!parse include Type
+
+        # @!method null?
+        #   Check if == +NULL+
+        #   @return [Boolean]
+
+        # @!method undef?
+        #   Check if == +UNDEF+
+        #   @return [Boolean]
+      end
+    end
+  end
+end

data/lib/openhab/dsl/types/up_down_type.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.UpDownType
+
+      # Adds methods to core OpenHAB UpDownType to make it more natural in Ruby
+      class UpDownType
+        # @!parse include Type
+
+        # @!method up?
+        #   Check if == +UP+
+        #   @return [Boolean]
+
+        # @!method down?
+        #   Check if == +DOWN+
+        #   @return [Boolean]
+
+        #
+        # Invert the type
+        #
+        # @return [UpDownType] +UP+ if +DOWN+, +DOWN+ if +UP+
+        #
+        def !
+          return UP if down?
+          return DOWN if up?
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/units.rb

@@ -10,7 +10,6 @@ end
 
 Object.send(:remove_const, :QuantityType)
 java_import org.openhab.core.library.types.QuantityType
-java_import org.openhab.core.types.util.UnitUtils
 
 module OpenHAB
   module DSL
@@ -18,6 +17,13 @@ module OpenHAB
     # Provides support for interacting with OpenHAB Units of Measurement
     #
     module Units
+      # @return The default unit for the current thread
+      def unit(unit = nil, &block)
+        return with_unit(unit, &block) if unit || block # back-compat
+
+        Thread.current[:unit]
+      end
+
       #
       # Sets a thread local variable to the supplied unit such that classes operating inside the block
       # can perform automatic conversions to the supplied unit for NumberItems
@@ -25,13 +31,12 @@ module OpenHAB
       # @param [Object] unit OpenHAB Unit or String representing unit
       # @yield [] Block executed in context of the supplied unit
       #
-      #
-      def unit(unit)
-        unit = UnitUtils.parse_unit(unit) if unit.is_a? String
-        Thread.current.thread_variable_set(:unit, unit)
+      def with_unit(unit)
+        unit = org.openhab.core.types.util.UnitUtils.parse_unit(unit) if unit.is_a? String
+        Thread.current[:unit] = unit
         yield
       ensure
-        Thread.current.thread_variable_set(:unit, nil)
+        Thread.current[:unit] = nil
       end
     end
   end

data/lib/openhab/version.rb

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