openhab-scripting 4.46.2 → 5.0.0

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

@@ -1,32 +1,18 @@
 # frozen_string_literal: true
 
-require 'forwardable'
-require 'time'
-require 'java'
+require "forwardable"
+require "time"
+
+require_relative "type"
 
 module OpenHAB
-  module DSL
+  module Core
     module Types
       DateTimeType = org.openhab.core.library.types.DateTimeType
 
-      # global alias - required for jrubyscripting addon <= OH3.2.0
-      ::DateTimeType = DateTimeType if ::DateTimeType.is_a?(java.lang.Class)
-
-      # @deprecated
-      # Backwards-compatible alias
-      DateTime = DateTimeType
-
-      # rubocop: disable Metrics/ClassLength class has a single responsibility
-
-      #
-      # Add methods to core OpenHAB DateTimeType to make it behave as a Ruby
-      # Time object
-      #
-      # Any method not explicitly defined is forwarded to the +ZonedDateTime+
-      # or +Time+ representation of this object as appropriate.
-      #
+      # {DateTimeType} uses a {ZonedDateTime} internally.
       class DateTimeType
-        # @!parse include Type
+        # @!parse include Command, State
 
         # remove the JRuby default == so that we can inherit the Ruby method
         remove_method :==
@@ -47,8 +33,8 @@ module OpenHAB
 
         class << self
           #
-          # Parses a String representing a time into an OpenHAB DateTimeType. First tries to parse it
-          #   using java's DateTimeType's parser, then falls back to the Ruby Time.parse
+          # Parses a String representing a time into a {DateTimeType}. First tries to parse it
+          #   using Java's parser, then falls back to the Ruby `Time.parse`.
           #
           # @param [String] time_string
           #
@@ -57,32 +43,25 @@ module OpenHAB
           def parse(time_string)
             time_string = "#{time_string}Z" if TIME_ONLY_REGEX.match?(time_string)
             DateTimeType.new(time_string)
-          rescue java.lang.StringIndexOutOfBoundsException, java.lang.IllegalArgumentException
-            # Try ruby's Time.parse if OpenHAB's DateTimeType parser fails
+          rescue java.lang.StringIndexOutOfBoundsException, java.lang.IllegalArgumentException => e
+            # Try Ruby's Time.parse if DateTimeType parser fails
             begin
-              DateTimeType.new(::Time.parse(time_string))
+              DateTimeType.new(::Time.parse(time_string).to_zoned_date_time)
             rescue ArgumentError
-              raise ArgumentError, "Unable to parse #{time_string} into a DateTimeType"
+              raise ArgumentError, e.message
             end
           end
+        end
 
-          # parses a String representing a duration
-          #
-          # for internal use
-          #
-          # @return [java.time.Duration]
-          #
-          # @!visibility private
-          def parse_duration(time_string)
-            # convert from common HH:MM to ISO8601 for parsing
-            if (match = time_string.match(TIME_ONLY_REGEX))
-              time_string = "PT#{match[:hours]}H#{match[:minutes]}M#{match[:seconds] || 0}S"
-            end
-            java.time.Duration.parse(time_string)
-          end
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in missing
+        #   fields during conversion. Not used in this class.
+        # @return [ZonedTimeTime]
+        def to_zoned_date_time(context = nil) # rubocop:disable Lint/UnusedMethodArgument
+          zoned_date_time
         end
 
-        # act like a ruby Time
+        # act like a Ruby Time
         def_delegator :zoned_date_time, :month_value, :month
         def_delegator :zoned_date_time, :day_of_month, :mday
         def_delegator :zoned_date_time, :day_of_year, :yday
@@ -90,32 +69,29 @@ module OpenHAB
         def_delegator :zoned_date_time, :second, :sec
         def_delegator :zoned_date_time, :nano, :nsec
         def_delegator :zoned_date_time, :to_epoch_second, :to_i
+        def_delegator :zoned_date_time, :to_time
 
-        alias day mday
+        # @!visibility private
+        alias_method :day, :mday
 
         #
         # Create a new instance of DateTimeType
         #
-        # @param value [ZonedDateTime, Time, String, Numeric]
+        # @param value [#to_zoned_date_time, #to_time, #to_str, #to_d, nil]
         #
-        def initialize(value = nil) # rubocop:disable Metrics
-          if value.respond_to?(:to_time)
-            time = value.to_time
-            instant = java.time.Instant.ofEpochSecond(time.to_i, time.nsec)
-            zone_id = java.time.ZoneId.of_offset('UTC', java.time.ZoneOffset.of_total_seconds(time.utc_offset))
-            super(ZonedDateTime.ofInstant(instant, zone_id))
+        def initialize(value = nil)
+          if value.respond_to?(:to_zoned_date_time)
+            super(value.to_zoned_date_time)
+            return
+          elsif value.respond_to?(:to_time)
+            super(value.to_time.to_zoned_date_time)
             return
           elsif value.respond_to?(:to_str)
             # strings respond_do?(:to_d), but we want to avoid that conversion
             super(value.to_str)
             return
           elsif value.respond_to?(:to_d)
-            time = value.to_d
-            super(ZonedDateTime.ofInstant(
-              java.time.Instant.ofEpochSecond(time.to_i,
-                                              ((time % 1) * 1_000_000_000).to_i),
-              java.time.ZoneId.systemDefault
-            ))
+            super(Time.at(value.to_d).to_zoned_date_time)
             return
           end
 
@@ -125,7 +101,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)
@@ -136,31 +112,19 @@ module OpenHAB
         #
         # Comparison
         #
-        # @param [DateTimeType, Items::DateTimeItem, Time,
-        #         String] other object to compare to
+        # @param [Object] 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?(self.class)
-            zoned_date_time.to_instant.compare_to(other.zoned_date_time.to_instant)
-          elsif other.is_a?(Items::DateTimeItem) ||
-                (other.is_a?(Items::GroupItem) && other.base_item.is_a?(Items::DateTimeItem))
-            return nil unless other.state?
-
-            zoned_date_time.to_instant.compare_to(other.state.zoned_date_time.to_instant)
-          elsif other.is_a?(TimeOfDay::TimeOfDay) || other.is_a?(TimeOfDay::TimeOfDayRangeElement)
-            to_tod <=> other
+            zoned_date_time <=> other.zoned_date_time
           elsif other.respond_to?(:to_time)
             to_time <=> other.to_time
-          elsif other.respond_to?(:to_str)
-            time_string = other.to_str
-            time_string = "#{time_string}T00:00:00#{zone}" if DATE_ONLY_REGEX.match?(time_string)
-            self <=> DateTimeType.parse(time_string)
           elsif other.respond_to?(:coerce)
             return nil unless (lhs, rhs = other.coerce(self))
 
@@ -173,42 +137,16 @@ module OpenHAB
         #
         # Coerce object to a DateTimeType
         #
-        # @param [Items::DateTimeItem, Time] other object to coerce to a
-        #   DateTimeType
+        # @param [Time] other object to coerce to a DateTimeType
         #
-        # @return [[DateTimeType, DateTimeType]]
+        # @return [[DateTimeType, DateTimeType], nil]
         #
         def coerce(other)
           logger.trace("Coercing #{self} as a request from #{other.class}")
-          if other.is_a?(Items::DateTimeItem)
-            return unless other.state?
-
-            [other.state, self]
-          elsif other.respond_to?(:to_time)
-            [DateTimeType.new(other), self]
-          end
-        end
-
-        #
-        # Convert this DateTimeType to a ruby Time object
-        #
-        # @return [Time] A Time object representing the same instant and timezone
-        #
-        def to_time
-          ::Time.at(to_i, nsec, :nsec).localtime(utc_offset)
+          return [other, zoned_date_time] if other.respond_to?(:to_zoned_date_time)
+          return [DateTimeType.new(other), self] if other.respond_to?(:to_time)
         end
 
-        #
-        # Convert the time part of this DateTimeType to a TimeOfDay object
-        #
-        # @return [TimeOfDay] A TimeOfDay object representing the time
-        #
-        def to_time_of_day
-          TimeOfDay::TimeOfDay.new(h: hour, m: minute, s: second)
-        end
-
-        alias to_tod to_time_of_day
-
         #
         # Returns the value of time as a floating point number of seconds since the Epoch
         #
@@ -230,7 +168,7 @@ module OpenHAB
         #
         # Returns true if time represents a time in UTC (GMT)
         #
-        # @return [Boolean] true if utc_offset == 0, false otherwise
+        # @return [true,false] true if utc_offset == 0, false otherwise
         #
         def utc?
           utc_offset.zero?
@@ -263,7 +201,7 @@ module OpenHAB
         end
 
         #
-        # Forward missing methods to the +ZonedDateTime+ object or a ruby +Time+
+        # Forward missing methods to the `ZonedDateTime` object or a ruby `Time`
         # object representing the same instant
         #
         def method_missing(method, *args, &block)
@@ -275,17 +213,14 @@ module OpenHAB
 
         # Add other to self
         #
-        # @param other [java.time.Duration, String, Numeric]
+        # @param other [Duration, Numeric]
         #
         # @return [DateTimeType]
-        def +(other) # rubocop:disable Metrics
-          if other.is_a?(java.time.Duration)
+        def +(other)
+          if other.is_a?(Duration)
             DateTimeType.new(zoned_date_time.plus(other))
-          elsif other.respond_to?(:to_str)
-            other = self.class.parse_duration(other.to_str)
-            self + other
           elsif other.respond_to?(:to_d)
-            DateTimeType.new(zoned_date_time.plusNanos((other.to_d * 1_000_000_000).to_i))
+            DateTimeType.new(zoned_date_time.plus_nanos((other.to_d * 1_000_000_000).to_i))
           elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(to_d))
             lhs + rhs
           else
@@ -301,24 +236,16 @@ module OpenHAB
         # if other is a DateTime-like object, the result is a Duration
         # representing how long between the two instants in time.
         #
-        # @param other [java.time.Duration, Time, String, Numeric]
+        # @param other [Duration, Time, Numeric]
         #
-        # @return [DateTimeType, java.Time.Duration]
-        def -(other) # rubocop:disable Metrics
-          if other.is_a?(java.time.Duration)
+        # @return [DateTimeType, Duration]
+        def -(other)
+          if other.is_a?(Duration)
             DateTimeType.new(zoned_date_time.minus(other))
           elsif other.respond_to?(:to_time)
             to_time - other.to_time
-          elsif other.respond_to?(:to_str)
-            time_string = other.to_str
-            other = if TIME_ONLY_REGEX.match?(time_string)
-                      self.class.parse_duration(time_string)
-                    else
-                      DateTimeType.parse(time_string)
-                    end
-            self - other
           elsif other.respond_to?(:to_d)
-            DateTimeType.new(zoned_date_time.minusNanos((other.to_d * 1_000_000_000).to_i))
+            DateTimeType.new(zoned_date_time.minus_nanos((other.to_d * 1_000_000_000).to_i))
           elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(to_d))
             lhs - rhs
           else
@@ -326,7 +253,8 @@ module OpenHAB
           end
         end
       end
-      # rubocop: enable Metrics/ClassLength
     end
   end
 end
+
+# @!parse DateTimeType = OpenHAB::Core::Types::DateTimeType

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

@@ -1,32 +1,51 @@
 # frozen_string_literal: true
 
-require_relative 'comparable_type'
-require_relative 'numeric_type'
+require_relative "comparable_type"
+require_relative "numeric_type"
+
+require_relative "type"
 
 module OpenHAB
-  module DSL
+  module Core
     module Types
       DecimalType = org.openhab.core.library.types.DecimalType
 
       #
-      # Add methods to core OpenHAB DecimalType to make it behave as a Ruby
-      # BigDecimal object
+      # {DecimalType} uses a {java.math.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
       #
-      # Any method not explicitly defined is forwarded to the +BigDecimal+
-      # representation of this object.
+      # @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 Type
+        # @!parse include Command, State
         include NumericType
         include ComparableType
 
+        #
+        # @!method initialize(value)
         #
         # Create a new instance of DecimalType
         #
-        # @param [java.math.BigDecimal, Items::NumericItem, Numeric] args Create a DecimalType from the given value
+        # @param [java.math.BigDecimal, Numeric] value Create a DecimalType from the given value
         #
-        def initialize(*args) # rubocop:disable Metrics
+        def initialize(*args)
           unless args.length == 1
             super
             return
@@ -39,9 +58,6 @@ module OpenHAB
             super(value.to_java.strip_trailing_zeros)
           elsif value.is_a?(DecimalType)
             super(value.to_big_decimal)
-          elsif value.is_a?(Items::NumericItem) ||
-                (value.is_a?(Items::GroupItem) && value.base_item.is_a?(Items::NumericItem))
-            super(value.state)
           elsif value.respond_to?(:to_d)
             super(value.to_d.to_java.strip_trailing_zeros)
           else # rubocop:disable Lint/DuplicateBranch
@@ -54,9 +70,9 @@ module OpenHAB
         #
         # Convert DecimalType to a QuantityType
         #
-        # @param [Object] other String or Unit representing an OpenHAB Unit
+        # @param [String, javax.measure.units.Unit] other
         #
-        # @return [QuantityType] +self+ as a {QuantityType} of the supplied Unit
+        # @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)
@@ -66,25 +82,20 @@ module OpenHAB
         #
         # Comparison
         #
-        # @param [NumericType, Items::NumericItem, Numeric]
+        # @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?(QuantityType)
+          if other.is_a?(QuantityType) || other.is_a?(HSBType)
             (other <=> self)&.-@
           elsif 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_d)
             to_d <=> other.to_d
           elsif other.respond_to?(:coerce)
@@ -97,28 +108,17 @@ module OpenHAB
         #
         # Type Coercion
         #
-        # Coerce object to a DecimalType
+        # Coerce object to a {DecimalType DecimalType}
         #
-        # @param [Items::NumericItem, Numeric, Type] other object to
-        #   coerce to a {DecimalType}
+        # @param [Numeric] 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]
         #
-        # @return [[DecimalType, DecimalType]]
-        #
-        def coerce(other) # rubocop:disable Metrics
+        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?
+          return unless other.respond_to?(:to_d)
 
-            [other.state, self]
-          elsif other.is_a?(Type)
-            [other, as(other.class)]
-          elsif other.respond_to?(:to_d)
-            [self.class.new(other.to_d), self]
-          end
+          [self.class.new(other.to_d), self]
         end
 
         #
@@ -132,12 +132,12 @@ module OpenHAB
         end
 
         {
-          :add => :+,
-          :subtract => :-,
-          :multiply => :*,
-          :divide => :/,
-          :remainder => :%,
-          :pow => :**
+          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)
@@ -183,3 +183,5 @@ module OpenHAB
     end
   end
 end
+
+# @!parse DecimalType = OpenHAB::Core::Types::DecimalType