openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/{dsl → core}/types/hsb_type.rb

@@ -1,23 +1,27 @@
 # frozen_string_literal: true
 
-require 'java'
-require_relative 'percent_type'
+require_relative "percent_type"
+
+require_relative "type"
 
 module OpenHAB
-  module DSL
+  module Core
     module Types
       HSBType = org.openhab.core.library.types.HSBType
 
-      # global alias - required for jrubyscripting addon <= OH3.2.0
-      ::HSBType = HSBType if ::HSBType.is_a?(java.lang.Class)
-
-      # Adds methods to core OpenHAB HSBType to make it more natural in Ruby
+      # {HSBType} is a complex type with constituents for hue, saturation and
+      #  brightness and can be used for color items.
       class HSBType < PercentType
-        # @!parse BLACK = BLACK # @return [HSBType]
-        # @!parse WHITE = WHITE # @return [HSBType]
-        # @!parse RED = RED # @return [HSBType]
-        # @!parse GREEN = GREEN # @return [HSBType]
-        # @!parse BLUE = BLUE # @return [HSBType]
+        # @!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 :|
@@ -53,11 +57,11 @@ module OpenHAB
 
           # add additional "overloads" to the constructor
           # @!visibility private
-          def new(*args) # rubocop:disable Metrics
+          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
+              # 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) }
@@ -73,12 +77,12 @@ module OpenHAB
             return super unless args.length == 3
 
             # convert from several numeric-like types to the exact types
-            # OpenHAB needs
+            # openHAB needs
             hue = args[0]
             args[0] = if hue.is_a?(DecimalType)
                         hue
                       elsif hue.is_a?(QuantityType)
-                        DecimalType.new(hue.to_unit(org.openhab.core.library.unit.Units::DEGREE_ANGLE).to_big_decimal)
+                        DecimalType.new(hue.to_unit(Units::DEGREE_ANGLE).to_big_decimal)
                       elsif hue.respond_to?(:to_d)
                         DecimalType.new(hue)
                       end
@@ -97,49 +101,18 @@ module OpenHAB
         #
         # Comparison
         #
-        # @param [NumericType, Items::NumericItem, Items::ColorItem, Numeric, String]
+        # @param [NumericType, Numeric]
         #   other object to compare to
         #
-        # @return [Integer, nil] -1, 0, +1 depending on whether +other+ is
+        # @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
+        #   `nil` is returned if the two values are incomparable.
         #
-        def <=>(other) # rubocop:disable Metrics
+        def <=>(other)
           logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
-          if other.is_a?(Items::ColorItem) ||
-             (other.is_a?(Items::GroupItem) && other.base_item.is_a?(ColorItem))
-            return nil unless other.state?
-
-            self <=> other.state
-          elsif other.is_a?(HSBType)
-            to_a <=> other.to_a
-          elsif other.respond_to?(:to_str)
-            self <=> HSBType.new(other)
-          else
-            super
-          end
-        end
-
-        #
-        # Type Coercion
-        #
-        # Coerce object to a HSBType
-        #
-        # @param [NumericType, Items::NumericItem, Items::ColorItem, Numeric, String]
-        #   other object to coerce to a HSBType
-        #
-        # @return [[HSBType, HSBType]]
-        #
-        def coerce(other)
-          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))
-            return unless other.state?
-
-            [other.state, self]
-          elsif other.respond_to?(:to_str)
-            [HSBType.new(other.to_str), self]
+          if other.is_a?(HSBType)
+            [brightness, hue, saturation] <=> [other.brightness, other.hue, other.saturation]
           else
             super
           end
@@ -147,12 +120,12 @@ module OpenHAB
 
         # rename raw methods so we can overwrite them
         # @!visibility private
-        alias raw_hue hue
+        alias_method :raw_hue, :hue
 
         # @!attribute [r] hue
-        # @return [QuantityType]
+        # @return [QuantityType] The color's hue component as a {QuantityType} of unit DEGREE_ANGLE.
         def hue
-          QuantityType.new(raw_hue.to_big_decimal, org.openhab.core.library.unit.Units::DEGREE_ANGLE)
+          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.
@@ -160,7 +133,7 @@ module OpenHAB
         # The alpha component is always 100%.
         #
         # @return [Integer]
-        alias argb rgb
+        alias_method :argb, :rgb
 
         # Convert to a packed 24-bit RGB value representing the color in the default sRGB color model.
         # @return [Integer]
@@ -169,9 +142,9 @@ module OpenHAB
         end
 
         # Convert to an HTML-style string of 6 hex characters in the default sRGB color model.
-        # @return [String] +'#xxxxxx'+
+        # @return [String] `"#xxxxxx"`
         def to_hex
-          Kernel.format('#%06x', rgb)
+          Kernel.format("#%06x", rgb)
         end
 
         # include units
@@ -180,29 +153,6 @@ module OpenHAB
           "#{hue},#{saturation},#{brightness}"
         end
 
-        #
-        # Convert the ColorItem to a hash
-        # @param [:hsb, :rgb] format for hash
-        # @return [Hash] in requested format
-        def to_h(format = :hsb)
-          values = to_a(format)
-          keys = (format == :hsb ? %i[hue saturation brightness] : %i[red green blue])
-          keys.zip(values).to_h
-        end
-
-        #
-        # Convert the ColorItem to an array of values
-        # @param [:hsb, :rgb] format for elements in the array
-        # @return [Array] of ColorItem components in requested format
-        def to_a(format = :hsb)
-          case format
-          when :hsb then [hue, saturation, brightness]
-          when :rgb then [red, green, blue].map(&:to_byte)
-          else
-            raise ArgumentError, "Unsupported format #{format}"
-          end
-        end
-
         # @!attribute [r] saturation
         #   @return [PercentType]
 
@@ -224,8 +174,10 @@ module OpenHAB
 
         # @!method to_xy
         #   Convert to the xyY values representing this object's color in CIE XY color model
-        #   @return [[PercentType, PercentType]]
+        #   @return [[PercentType, 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/{dsl → core}/types/numeric_type.rb

@@ -1,19 +1,23 @@
 # frozen_string_literal: true
 
-require 'bigdecimal'
-require 'forwardable'
+require "bigdecimal"
+require "bigdecimal/util"
+require "forwardable"
+
+require_relative "type"
 
 module OpenHAB
-  module DSL
+  module Core
     module Types
-      # Mixin for methods common to DecimalType and QuantityType
+      # Mixin for methods common to DecimalType and QuantityType.
       module NumericType
-        # apply meta-programming to including class
+        # @!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
@@ -21,7 +25,7 @@ module OpenHAB
         #
         # Check equality without type conversion
         #
-        # @return [Boolean] if the same value is represented, without type
+        # @return [true,false] if the same value is represented, without type
         #   conversion
         def eql?(other)
           return false unless other.instance_of?(self.class)
@@ -29,10 +33,19 @@ module OpenHAB
           compare_to(other).zero?
         end
 
-        # Unary plus
+        # @return [self]
         def +@
           self
         end
+
+        # @!method to_d
+        #   @return [BigDecimal]
+
+        # @!method to_i
+        #   @return [Integer]
+
+        # @!method to_f
+        #   @return [Float]
       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/{dsl → core}/types/percent_type.rb

@@ -1,59 +1,56 @@
 # frozen_string_literal: true
 
-require_relative 'decimal_type'
+require_relative "decimal_type"
 
 module OpenHAB
-  module DSL
+  module Core
     module Types
       PercentType = org.openhab.core.library.types.PercentType
 
-      # global alias - required for jrubyscripting addon <= OH3.2.0
-      ::PercentType = PercentType if ::PercentType.is_a?(java.lang.Class)
-
-      # Adds methods to core OpenHAB PercentType to make it more natural in Ruby
+      # {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+
+        # Check if {ON}
         #
-        # Note that +ON+ is defined as any value besides 0%.
+        # Note that {ON} is defined as any value besides 0%.
         #
-        # @return [Boolean]
+        # @return [true,false]
         #
         def on?
           as(OnOffType).on?
         end
 
         #
-        # Check if +OFF+
+        # Check if {OFF}
         #
-        # Note that +OFF+ is defined as 0% exactly.
+        # Note that {OFF} is defined as 0% exactly.
         #
-        # @return [Boolean]
+        # @return [true,false]
         #
         def off?
           as(OnOffType).off?
         end
 
         #
-        # Check if +UP+
+        # Check if {UP}
         #
-        # Note that +UP+ is defined as 0% exactly.
+        # Note that {UP} is defined as 0% exactly.
         #
-        # @return [Boolean]
+        # @return [true,false]
         #
         def up?
           !!as(UpDownType)&.up?
         end
 
         #
-        # Check if +DOWN+
+        # Check if {DOWN}
         #
-        # Note that +DOWN+ is defined as 100% exactly.
+        # Note that {DOWN} is defined as 100% exactly.
         #
-        # @return [Boolean]
+        # @return [true,false]
         #
         def down?
           !!as(UpDownType)&.down?
@@ -71,9 +68,9 @@ module OpenHAB
         # @param range [Range] the range as a numeric
         # @return [Numeric] the value as a percentage of the range
         #
-        def scale(range) # rubocop:disable Metrics/AbcSize
+        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'
+            raise ArgumentError, "range must be a Range of Numerics"
           end
 
           result = (to_d * (range.max - range.min) / 100) + range.min
@@ -94,3 +91,5 @@ module OpenHAB
     end
   end
 end
+
+# @!parse PercentType = OpenHAB::Core::Types::PercentType

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      PlayPauseType = org.openhab.core.library.types.PlayPauseType
+
+      # Implements {PLAY} and {PAUSE} commands and states.
+      class PlayPauseType # rubocop:disable Lint/EmptyClass
+        # @!parse include Command, State
+
+        # @!constant PLAY
+        #   Play Command/Playing State
+        # @!constant PAUSE
+        #   Pause Command/Paused State
+
+        # @!method playing?
+        #   Check if `self == PLAY`
+        #   @return [true,false]
+
+        # @!parse alias play? playing?
+
+        # @!method paused?
+        #   Check if `self == PAUSE`
+        #   @return [true,false]
+
+        # @!parse alias pause? paused?
+      end
+    end
+  end
+end
+
+# @!parse
+#   PlayPauseType = OpenHAB::Core::Types::PlayPauseType
+#   PLAY = OpenHAB::Core::Types::PlayPauseType::PLAY
+#   PAUSE = OpenHAB::Core::Types::PlayPauseType::PAUSE

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "type"
+
+module OpenHAB
+  module Core
+    module Types
+      PointType = org.openhab.core.library.types.PointType
+
+      # {PointType} can be used for items that are dealing with GPS or location awareness functionality.
+      class PointType
+        # @!parse include Command, State
+
+        # @overload initialize(latitude, longitude, altitude)
+        #   @param [DecimalType, QuantityType, StringType, Numeric] latitude
+        #   @param [DecimalType, QuantityType, StringType, Numeric] longitude
+        #   @param [DecimalType, QuantityType, StringType, Numeric] altitude
+        def initialize(*args)
+          if (2..3).cover?(args.length)
+            args = args.each_with_index.map do |value, index|
+              if value.is_a?(DecimalType) || value.is_a?(StringType)
+                value
+              elsif value.is_a?(QuantityType)
+                unit = (index == 2) ? DSL.unit(SIUnits::METRE.dimension) || SIUnits::METRE : Units::DEGREE_ANGLE
+                DecimalType.new(value.to_unit(unit).to_big_decimal)
+              elsif value.respond_to?(:to_str)
+                StringType.new(value.to_str)
+              elsif value.respond_to?(:to_d)
+                DecimalType.new(value)
+              end
+            end
+          end
+
+          super(*args)
+        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)
+
+          equals(other)
+        end
+
+        #
+        # Check equality with type conversion
+        #
+        # @param [PointType, String]
+        #   other object to compare to
+        #
+        # @return [true,false]
+        #
+        def ==(other)
+          logger.trace { "(#{self.class}) #{self} == #{other} (#{other.class})" }
+          if other.instance_of?(self.class)
+            equals(other)
+          elsif other.respond_to?(:coerce)
+            return false unless (lhs, rhs = other.coerce(self))
+
+            lhs == rhs
+          end
+        end
+
+        # rename raw methods so we can overwrite them
+        # @!visibility private
+        alias_method :raw_latitude, :latitude
+        # .
+        # @!visibility private
+        alias_method :raw_longitude, :longitude
+        # .
+        # @!visibility private
+        alias_method :raw_altitude, :altitude
+        # .
+        # @!visibility private
+        alias_method :raw_distance_from, :distance_from
+
+        # @!attribute [r] latitude
+        # @return [QuantityType]
+        def latitude
+          QuantityType.new(raw_latitude.to_big_decimal, SIUnits::DEGREE_ANGLE)
+        end
+
+        # @!attribute [r] longitude
+        # @return [QuantityType]
+        def longitude
+          QuantityType.new(raw_longitude.to_big_decimal, SIUnits::DEGREE_ANGLE)
+        end
+
+        # @!attribute [r] altitude
+        # @return [QuantityType]
+        def altitude
+          QuantityType.new(raw_altitude.to_big_decimal, Units::METRE)
+        end
+
+        #
+        # Calculate the distance in meters from other, ignoring altitude.
+        #
+        # This algorithm also ignores the oblate spheroid shape of Earth and
+        # assumes a perfect sphere, so results are inexact.
+        #
+        # @return [QuantityType]
+        def distance_from(other)
+          logger.trace("(#{self}).distance_from(#{other} (#{other.class})")
+          raise TypeError, "#{other.class} can't be coerced into #{self.class}" unless other.is_a?(PointType)
+
+          QuantityType.new(raw_distance_from(other), SIUnits::METRE)
+        end
+        alias_method :-, :distance_from
+      end
+    end
+  end
+end
+
+# @!parse PointType = OpenHAB::Core::Types::PointType