openhab-jrubyscripting 5.0.0.rc1

data/lib/openhab/core/types/decimal_type.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative "comparable_type"
+require_relative "numeric_type"
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      DecimalType = org.openhab.core.library.types.DecimalType
+
+      #
+      # {DecimalType} uses a {java.lang.BigDecimal} internally and thus can be
+      # used for integers, longs and floating point numbers alike.
+      #
+      # @example DecimalType can be used in case statements with ranges
+      #   # Check if number item is less than 50
+      #   case NumberOne.state
+      #   when (0...50)
+      #     logger.info("#{NumberOne} is less than 50")
+      #   when (50..100)
+      #     logger.info("#{NumberOne} is greater than 50")
+      #   end
+      #
+      # @example DecimalType can be compared directly against Numeric
+      #   if NumberOne.state > 10
+      #     logger.info("Item #{NumberOne.name} is greater than 10")
+      #   end
+      #
+      # @example DecimalType can be compared against the value of another DecimalType
+      #   if NumberOne.state > NumberTwo.state
+      #     logger.info("Item #{NumberOne} (#{NumberOne.state}) is greater than #{NumberTwo} (#{NumberTwo.state})")
+      #   end
+      #
+      class DecimalType
+        # @!parse include Command, State
+        include NumericType
+        include ComparableType
+
+        #
+        # @!method initialize(value)
+        #
+        # Create a new instance of DecimalType
+        #
+        # @param [java.math.BigDecimal, Numeric] value Create a DecimalType from the given value
+        #
+        def initialize(*args)
+          unless args.length == 1
+            super
+            return
+          end
+
+          value = args.first
+          if value.is_a?(java.math.BigDecimal)
+            super
+          elsif value.is_a?(BigDecimal)
+            super(value.to_java.strip_trailing_zeros)
+          elsif value.is_a?(DecimalType)
+            super(value.to_big_decimal)
+          elsif value.respond_to?(:to_d)
+            super(value.to_d.to_java.strip_trailing_zeros)
+          else # rubocop:disable Lint/DuplicateBranch
+            # duplicates the Java BigDecimal branch, but that needs to go first
+            # in order to avoid unnecessary conversions
+            super
+          end
+        end
+
+        #
+        # Convert DecimalType to a QuantityType
+        #
+        # @param [String, javax.measure.units.Unit] other
+        #
+        # @return [QuantityType] `self` as a {QuantityType} of the supplied Unit
+        #
+        def |(other)
+          other = org.openhab.core.types.util.UnitUtils.parse_unit(other.to_str) if other.respond_to?(:to_str)
+          QuantityType.new(to_big_decimal, other)
+        end
+
+        #
+        # Comparison
+        #
+        # @param [NumericType, Numeric]
+        #   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)
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          if other.is_a?(QuantityType) || other.is_a?(HSBType)
+            (other <=> self)&.-@
+          elsif other.is_a?(self.class)
+            compare_to(other)
+          elsif other.respond_to?(:to_d)
+            to_d <=> other.to_d
+          elsif other.respond_to?(:coerce)
+            return nil unless (lhs, rhs = other.coerce(self))
+
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a {DecimalType DecimalType}
+        #
+        # @param [Numeric, Type] other object to coerce to a {DecimalType DecimalType}
+        #
+        #   If `other` is a {Type}, `self` will instead be coerced
+        #   to that type to accomodate comparison with things such as {OnOffType}.
+        #
+        # @return [Array<(DecimalType, DecimalType)>, nil]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          if other.is_a?(Type)
+            [other, as(other.class)]
+          elsif other.respond_to?(:to_d)
+            [self.class.new(other.to_d), self]
+          end
+        end
+
+        #
+        # Unary minus
+        #
+        # Negates self
+        #
+        # @return [DecimalType]
+        def -@
+          self.class.new(to_big_decimal.negate)
+        end
+
+        {
+          add: :+,
+          subtract: :-,
+          multiply: :*,
+          divide: :/,
+          remainder: :%,
+          pow: :**
+        }.each do |java_op, ruby_op|
+          class_eval( # rubocop:disable Style/DocumentDynamicEvalDefinition https://github.com/rubocop/rubocop/issues/10179
+            # def +(other)
+            #   if other.is_a?(DecimalType)
+            #     self.class.new(to_big_decimal.add(other.to_big_decimal))
+            #   elsif other.is_a?(java.math.BigDecimal)
+            #     self.class.new(to_big_decimal.add(other))
+            #   elsif other.respond_to?(:to_d)
+            #     result = to_d + other
+            #     # result could already be a QuantityType
+            #     result = self.class.new(result) unless result.is_a?(NumericType)
+            #     result
+            #   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)
+                if other.is_a?(DecimalType)
+                  self.class.new(to_big_decimal.#{java_op}(other.to_big_decimal, java.math.MathContext::DECIMAL128))
+                elsif other.is_a?(java.math.BigDecimal)
+                  self.class.new(to_big_decimal.#{java_op}(other, java.math.MathContext::DECIMAL128))
+                elsif other.respond_to?(:to_d)
+                  result = to_d #{ruby_op} other
+                  # result could already be a QuantityType
+                  result = self.class.new(result) unless result.is_a?(NumericType)
+                  result
+                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
+
+        # any method that exists on BigDecimal gets forwarded to to_d
+        delegate (BigDecimal.instance_methods - instance_methods) => :to_d
+      end
+    end
+  end
+end
+
+# @!parse DecimalType = OpenHAB::Core::Types::DecimalType

data/lib/openhab/core/types/hsb_type.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "percent_type"
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      HSBType = org.openhab.core.library.types.HSBType
+
+      # {HSBType} is a complex type with constituents for hue, saturation and
+      #  brightness and can be used for color items.
+      class HSBType < PercentType
+        # @!constant BLACK
+        #   @return [HSBType]
+        # @!constant WHITE
+        #   @return [HSBType]
+        # @!constant RED
+        #   @return [HSBType]
+        # @!constant GREEN
+        #   @return [HSBType]
+        # @!constant BLUE
+        #   @return [HSBType]
+
+        # conversion to QuantityType doesn't make sense on HSBType
+        undef_method :|
+
+        remove_method :==
+
+        # r, g, b as an array of symbols
+        RGB_KEYS = %i[r g b].freeze
+        private_constant :RGB_KEYS
+
+        class << self
+          # @!method from_rgb(r, g, b)
+          #   Create HSBType from RGB values
+          #   @param r [Integer] Red component (0-255)
+          #   @param g [Integer] Green component (0-255)
+          #   @param b [Integer] Blue component (0-255)
+          #   @return [HSBType]
+
+          # @!method from_xy(x, y)
+          #   Create HSBType representing the provided xy color values in CIE XY color model
+          #   @param x [Float]
+          #   @param y [Float]
+          #   @return [HSBType]
+
+          # Create HSBType from hue, saturation, and brightness values
+          # @param hue [DecimalType, QuantityType, Numeric] Hue component (0-360º)
+          # @param saturation [PercentType, Numeric] Saturation component (0-100%)
+          # @param brightness [PercentType, Numeric] Brightness component (0-100%)
+          # @return [HSBType]
+          def from_hsb(hue, saturation, brightness)
+            new(hue, saturation, brightness)
+          end
+
+          # add additional "overloads" to the constructor
+          # @!visibility private
+          def new(*args)
+            if args.length == 1 && args.first.respond_to?(:to_str)
+              value = args.first.to_str
+
+              # parse some formats OpenHAB doesn't understand
+              # in this case, HTML hex format for rgb
+              if (match = value.match(/^#(\h{2})(\h{2})(\h{2})$/))
+                rgb = match.to_a[1..3].map { |v| v.to_i(16) }
+                logger.trace("creating from rgb #{rgb.inspect}")
+                return from_rgb(*rgb)
+              end
+            end
+
+            # Convert strings using java class
+            return value_of(args.first) if args.length == 1 && args.first.is_a?(String)
+
+            # use super constructor for empty args
+            return super unless args.length == 3
+
+            # convert from several numeric-like types to the exact types
+            # OpenHAB needs
+            hue = args[0]
+            args[0] = if hue.is_a?(DecimalType)
+                        hue
+                      elsif hue.is_a?(QuantityType)
+                        DecimalType.new(hue.to_unit(Units::DEGREE_ANGLE).to_big_decimal)
+                      elsif hue.respond_to?(:to_d)
+                        DecimalType.new(hue)
+                      end
+            args[1..2] = args[1..2].map do |v|
+              if v.is_a?(PercentType)
+                v
+              elsif v.respond_to?(:to_d)
+                PercentType.new(v)
+              end
+            end
+
+            super(*args)
+          end
+        end
+
+        #
+        # Comparison
+        #
+        # @param [NumericType, Numeric]
+        #   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)
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          if other.is_a?(HSBType)
+            [brightness, hue, saturation] <=> [other.brightness, other.hue, other.saturation]
+          else
+            super
+          end
+        end
+
+        # rename raw methods so we can overwrite them
+        # @!visibility private
+        alias_method :raw_hue, :hue
+
+        # @!attribute [r] hue
+        # @return [QuantityType] The color's hue component as a {QuantityType} of unit DEGREE_ANGLE.
+        def hue
+          QuantityType.new(raw_hue.to_big_decimal, Units::DEGREE_ANGLE)
+        end
+
+        # Convert to a packed 32-bit RGB value representing the color in the default sRGB color model.
+        #
+        # The alpha component is always 100%.
+        #
+        # @return [Integer]
+        alias_method :argb, :rgb
+
+        # Convert to a packed 24-bit RGB value representing the color in the default sRGB color model.
+        # @return [Integer]
+        def rgb
+          argb & 0xffffff
+        end
+
+        # Convert to an HTML-style string of 6 hex characters in the default sRGB color model.
+        # @return [String] +'#xxxxxx'+
+        def to_hex
+          Kernel.format("#%06x", rgb)
+        end
+
+        # include units
+        # @!visibility private
+        def to_s
+          "#{hue},#{saturation},#{brightness}"
+        end
+
+        # @!attribute [r] saturation
+        #   @return [PercentType]
+
+        # @!attribute [r] brightness
+        #   @return [PercentType]
+
+        # @!attribute [r] red
+        #   @return [PercentType]
+
+        # @!attribute [r] green
+        #   @return [PercentType]
+
+        # @!attribute [r] blue
+        #   @return [PercentType]
+
+        # @!method to_rgb
+        # Convert to RGB values representing the color in the default sRGB color model
+        # @return [[PercentType, PercentType, PercentType]]
+
+        # @!method to_xy
+        #   Convert to the xyY values representing this object's color in CIE XY color model
+        #   @return [[PercentType, PercentType]]
+      end
+    end
+  end
+end
+
+# @!parse HSBType = OpenHAB::Core::Types::HSBType

data/lib/openhab/core/types/increase_decrease_type.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      IncreaseDecreaseType = org.openhab.core.library.types.IncreaseDecreaseType
+
+      # Represents {INCREASE} and {DECREASE} commands.
+      class IncreaseDecreaseType # rubocop:disable Lint/EmptyClass
+        # @!parse include Command
+
+        # @!constant INCREASE
+        #   Increase Command
+        # @!constant DECREASE
+        #   Decrease Command
+
+        # @!method increase?
+        #   Check if `self == INCREASE`
+        #   @return [true,false]
+
+        # @!method decrease?
+        #   Check if `self == DECREASE`
+        #   @return [true,false]
+      end
+    end
+  end
+end
+
+# @!parse
+#   IncreaseDecreaseType = OpenHAB::Core::Types::IncreaseDecreaseType
+#   INCREASE = OpenHAB::Core::Types::IncreaseDecreaseType::INCREASE
+#   DECREASE = OpenHAB::Core::Types::IncreaseDecreaseType::DECREASE

data/lib/openhab/core/types/next_previous_type.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      NextPreviousType = org.openhab.core.library.types.NextPreviousType
+
+      # Implements {NEXT} and {PREVIOUS} commands.
+      class NextPreviousType # rubocop:disable Lint/EmptyClass
+        # @!parse include Command
+
+        # @!constant NEXT
+        #   Next Command
+        # @!constant PREVIOUS
+        #   Previous Command
+
+        # @!method next?
+        #   Check if `self == NEXT`
+        #   @return [true,false]
+
+        # @!method previous?
+        #   Check if `self == PREVIOUS`
+        #   @return [true,false]
+      end
+    end
+  end
+end
+
+# @!parse
+#   NextPreviousType = OpenHAB::Core::Types::NextPreviousType
+#   NEXT = OpenHAB::Core::Types::NextPreviousType::NEXT
+#   PREVIOUS = OpenHAB::Core::Types::NextPreviousType::PREVIOUS

data/lib/openhab/core/types/numeric_type.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+require "forwardable"
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      # Mixin for methods common to DecimalType and QuantityType.
+      module NumericType
+        # @!visibility private
+        def self.included(klass)
+          klass.extend Forwardable
+
+          klass.delegate %i[to_d zero?] => :to_big_decimal
+          klass.delegate %i[positive? negative? to_f to_i to_int hash] => :to_d
+
+          # remove the JRuby default == so that we can inherit the Ruby method
+          klass.remove_method :==
+        end
+
+        #
+        # Check equality without type conversion
+        #
+        # @return [true,false] if the same value is represented, without type
+        #   conversion
+        def eql?(other)
+          return false unless other.instance_of?(self.class)
+
+          compare_to(other).zero?
+        end
+
+        # @return [self]
+        def +@
+          self
+        end
+
+        # @!method to_d
+        #   @return [BigDecimal]
+
+        # @!method to_i
+        #   @return [Integer]
+
+        # @!method to_f
+        #   @return [Float]
+      end
+    end
+  end
+end

data/lib/openhab/core/types/on_off_type.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      OnOffType = org.openhab.core.library.types.OnOffType
+
+      #
+      # Implements {ON} and {OFF} commands and states.
+      #
+      # Also, {PercentType} can be converted to {OnOffType}
+      # for more semantic comparisons. `0` is {OFF}, anything
+      # else if {ON}.
+      #
+      class OnOffType
+        # @!parse include Command, State
+
+        # @!constant ON
+        #   On Command/State
+        # @!constant OFF
+        #   Off Command/State
+
+        # @!method on?
+        #   Check if `self == ON`
+        #   @return [true,false]
+
+        # @!method off?
+        #   Check if `self == OFF`
+        #   @return [true,false]
+
+        # Invert the type
+        # @return [OnOffType] {OFF} if {on?}, {ON} if {off?}
+        def !
+          on? ? OFF : ON
+        end
+      end
+    end
+  end
+end
+
+# @!parse
+#   OnOffType = OpenHAB::Core::Types::OnOffType
+#   ON = OpenHAB::Core::Types::OnOffType::ON
+#   OFF = OpenHAB::Core::Types::OnOffType::OFF

data/lib/openhab/core/types/open_closed_type.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      OpenClosedType = org.openhab.core.library.types.OpenClosedType
+
+      # Implements {OPEN} and {CLOSED} states.
+      class OpenClosedType
+        # @!parse include State
+
+        # @!constant OPEN
+        #   Open State
+        # @!constant CLOSED
+        #   Closed State
+
+        # @!method open?
+        #   Check if `self == OPEN`
+        #   @return [true,false]
+
+        # @!method closed?
+        #   Check if `self == CLOSED`
+        #   @return [true,false]
+
+        # Invert the type
+        # @return [OpenClosedType] {OPEN} if {closed?}, {CLOSED} if {open?}
+        def !
+          return CLOSED if open?
+          return OPEN if closed?
+        end
+      end
+    end
+  end
+end
+
+# @!parse
+#   OpenClosedType = OpenHAB::Core::Types::OpenClosedType
+#   OPEN = OpenHAB::Core::Types::OpenClosedType::OPEN
+#   CLOSED = OpenHAB::Core::Types::OpenClosedType::CLOSED

data/lib/openhab/core/types/percent_type.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "decimal_type"
+
+module OpenHAB
+  module Core
+    module Types
+      PercentType = org.openhab.core.library.types.PercentType
+
+      # {PercentType} extends {DecimalType} by putting constraints for its value on top (0-100).
+      class PercentType < DecimalType
+        # remove the JRuby default == so that we can inherit the Ruby method
+        remove_method :==
+
+        #
+        # Check if {ON}
+        #
+        # Note that {ON} is defined as any value besides 0%.
+        #
+        # @return [true,false]
+        #
+        def on?
+          as(OnOffType).on?
+        end
+
+        #
+        # Check if {OFF}
+        #
+        # Note that {OFF} is defined as 0% exactly.
+        #
+        # @return [true,false]
+        #
+        def off?
+          as(OnOffType).off?
+        end
+
+        #
+        # Check if {UP}
+        #
+        # Note that {UP} is defined as 0% exactly.
+        #
+        # @return [true,false]
+        #
+        def up?
+          !!as(UpDownType)&.up?
+        end
+
+        #
+        # Check if {DOWN}
+        #
+        # Note that {DOWN} is defined as 100% exactly.
+        #
+        # @return [true,false]
+        #
+        def down?
+          !!as(UpDownType)&.down?
+        end
+
+        # include the %
+        # @!visibility private
+        def to_s
+          "#{to_string}%"
+        end
+
+        #
+        # Scale the value to a particular range
+        #
+        # @param range [Range] the range as a numeric
+        # @return [Numeric] the value as a percentage of the range
+        #
+        def scale(range)
+          unless range.is_a?(Range) && range.min.is_a?(Numeric) && range.max.is_a?(Numeric)
+            raise ArgumentError, "range must be a Range of Numerics"
+          end
+
+          result = (to_d * (range.max - range.min) / 100) + range.min
+          case range.max
+          when Integer then result.round
+          when Float then result.to_f
+          else result
+          end
+        end
+
+        # scale the value to fit in a single byte
+        #
+        # @return [Integer] an integer in the range 0-255
+        def to_byte
+          scale(0..255)
+        end
+      end
+    end
+  end
+end
+
+# @!parse PercentType = OpenHAB::Core::Types::PercentType