openhab-scripting 4.1.4 → 4.5.0

data/lib/openhab/dsl/monkey_patch/ruby/string.rb

@@ -1,44 +1,44 @@
 # frozen_string_literal: true
 
-require 'openhab/dsl/types/quantity'
-require 'openhab/dsl/types/datetime'
-require 'openhab/dsl/items/datetime_item'
-
 module OpenHAB
   module DSL
+    # monkey patches
     module MonkeyPatch
+      # extensions to core Ruby objects
       module Ruby
-        #
-        # Extend String class
-        #
+        # extend String class so that it will do semantic comparisons against
+        # DateTimeType and QuantityType, instead of converting the latter to
+        # String and doing an exact match
         module StringExtensions
-          include OpenHAB::Core
-
-          #
-          # Compares String to another object
-          #
-          # @param [Object] other object to compare to
-          #
-          # @return [Boolean]  true if the two objects contain the same value, false otherwise
-          #
+          # {include:StringExtensions}
           def ==(other)
             case other
-            when OpenHAB::DSL::Types::Quantity, QuantityType, Java::OrgOpenhabCoreLibraryTypes::StringType,
-              OpenHAB::DSL::Types::DateTime, OpenHAB::DSL::Items::DateTimeItem
+            when Types::QuantityType,
+              Types::DateTimeType,
+              Items::DateTimeItem,
+              Items::NumericItem
               other == self
             else
               super
             end
           end
+
+          # {include:StringExtensions}
+          def <=>(other)
+            case other
+            when Types::QuantityType,
+              Types::DateTimeType,
+              Items::DateTimeItem,
+              Items::NumericItem
+              (other <=> self)&.-@()
+            else
+              super
+            end
+          end
         end
       end
     end
   end
 end
 
-#
-# Prepend String class with comparison extensions
-#
-class String
-  prepend OpenHAB::DSL::MonkeyPatch::Ruby::StringExtensions
-end
+String.prepend(OpenHAB::DSL::MonkeyPatch::Ruby::StringExtensions)

data/lib/openhab/dsl/rules/terse.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    module Rules
+      # Module containing terse rule stubs
+      module Terse
+        %i[changed channel cron every updated received_command].each do |trigger|
+          class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+            def #{trigger}(*args, name: nil, **kwargs, &block)                   # def changed(*args, name: nil, **kwargs, &block)
+              # if no name is given, just default to the name of the rules file  #   # if no name is given, just default to the name of the rules file
+              name ||= File.basename(caller_locations.last.path)                 #   name ||= File.basename(caller_locations.last.path)
+              rule name do                                                       #   rule name do
+                #{trigger}(*args, **kwargs)                                      #     changed(*args, **kwargs)
+                run(&block)                                                      #     run(&block)
+              end                                                                #   end
+            end                                                                  # end
+            module_function #{trigger.inspect}                                   # module_function :changed
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/states.rb

@@ -48,7 +48,7 @@ module OpenHAB
       # @return [StateStorage] item states
       #
       def store_states(*items)
-        items = items.flatten.map { |item| item.respond_to?(:oh_item) ? item.oh_item : item }
+        items = items.flatten
         states = StateStorage.new(BusEvent.storeStates(*items).to_h)
         if block_given?
           yield

data/lib/openhab/dsl/time_of_day.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-require 'java'
 require 'openhab/log/logger'
-require 'openhab/dsl/items/datetime_item'
-require 'openhab/dsl/types/datetime'
+require 'openhab/dsl/types/date_time_type'
 require 'time'
 
 module OpenHAB
@@ -173,7 +171,7 @@ module OpenHAB
           case object
           when TimeOfDay then adjust_second_of_day(object.local_time.to_second_of_day)
           when String then adjust_second_of_day(TimeOfDay.parse(object).local_time.to_second_of_day)
-          when Time, OpenHAB::DSL::Types::DateTime, OpenHAB::DSL::Items::DateTimeItem
+          when Time, OpenHAB::DSL::Types::DateTimeType, OpenHAB::DSL::Items::DateTimeItem
             adjust_second_of_day(TimeOfDay.new(h: object.hour, m: object.min, s: object.sec)
             .local_time.to_second_of_day)
           when TimeOfDayRangeElement then object.sod
@@ -218,7 +216,7 @@ module OpenHAB
       private_class_method def to_time_of_day(object)
         case object
         when String then TimeOfDay.parse(object)
-        when Time, OpenHAB::DSL::Types::DateTime, OpenHAB::DSL::Items::DateTimeItem
+        when Time, OpenHAB::DSL::Types::DateTimeType, OpenHAB::DSL::Items::DateTimeItem
           TimeOfDay.new(h: object.hour, m: object.min, s: object.sec)
         else object
         end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    # Comparable#== is overwritten by Type, because DecimalType etc.
+    # inherits from Comparable on the Java side, so it's in the wrong place
+    # in the ancestor list
+    # @!visibility private
+    module ComparableType
+      # re-implement
+      # @!visibility private
+      def ==(other)
+        r = self <=> other
+
+        return false if r.nil?
+
+        r.zero?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'time'
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.DateTimeType
+
+      # global alias
+      ::DateTimeType = DateTimeType
+
+      # @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.
+      #
+      class DateTimeType
+        # @!parse include Type
+
+        # remove the JRuby default == so that we can inherit the Ruby method
+        remove_method :==
+
+        extend Forwardable
+        include Comparable
+
+        #
+        # Regex expression to identify strings defining a time in hours, minutes and optionally seconds
+        #
+        TIME_ONLY_REGEX = /\A(?<hours>\d\d):(?<minutes>\d\d)(?<seconds>:\d\d)?\Z/.freeze
+
+        #
+        # Regex expression to identify strings defining a time in year, month, and day
+        #
+        DATE_ONLY_REGEX = /\A\d{4}-\d\d-\d\d\Z/.freeze
+        private_constant :TIME_ONLY_REGEX, :DATE_ONLY_REGEX
+
+        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
+          #
+          # @param [String] time_string
+          #
+          # @return [DateTimeType]
+          #
+          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
+            begin
+              DateTimeType.new(Time.parse(time_string))
+            rescue ArgumentError
+              raise ArgumentError, "Unable to parse #{time_string} into a DateTimeType"
+            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
+        end
+
+        # 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
+        def_delegator :zoned_date_time, :minute, :min
+        def_delegator :zoned_date_time, :second, :sec
+        def_delegator :zoned_date_time, :nano, :nsec
+        def_delegator :zoned_date_time, :to_epoch_second, :to_i
+
+        alias day mday
+
+        #
+        # Create a new instance of DateTimeType
+        #
+        # @param value [ZonedDateTime, Time, String, Numeric]
+        #
+        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))
+            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
+            ))
+            return
+          end
+
+          super
+        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)
+
+          zoned_date_time.compare_to(other.zoned_date_time).zero?
+        end
+
+        #
+        # Comparison
+        #
+        # @param [DateTimeType, Items::DateTimeItem, Time,
+        #         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)
+            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
+          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)
+            lhs, rhs = other.coerce(self)
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a DateTimeType
+        #
+        # @param [Items::DateTimeItem, Time] other object to coerce to a
+        #   DateTimeType
+        #
+        # @return [[DateTimeType, DateTimeType]]
+        #
+        def coerce(other)
+          logger.trace("Coercing #{self} as a request from #{other.class}")
+          if other.is_a?(Items::DateTimeItem)
+            raise TypeError, "can't convert #{UnDefType} into #{self.class}" unless other.state?
+
+            [other.state, self]
+          elsif other.respond_to?(:to_time)
+            [DateTimeType.new(other), self]
+          else
+            raise TypeError, "can't convert #{other.class} into #{self.class}"
+          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)
+        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
+        #
+        # @return [Float] Number of seconds since the Epoch, with nanosecond presicion
+        #
+        def to_f
+          zoned_date_time.to_epoch_second + (zoned_date_time.nano / 1_000_000_000)
+        end
+
+        #
+        # The offset in seconds from UTC
+        #
+        # @return [Integer] The offset from UTC, in seconds
+        #
+        def utc_offset
+          zoned_date_time.offset.total_seconds
+        end
+
+        #
+        # Returns true if time represents a time in UTC (GMT)
+        #
+        # @return [Boolean] true if utc_offset == 0, false otherwise
+        #
+        def utc?
+          utc_offset.zero?
+        end
+
+        #
+        # Returns an integer representing the day of the week, 0..6, with Sunday == 0.
+        #
+        # @return [Integer] The day of week
+        #
+        def wday
+          zoned_date_time.day_of_week.value % 7
+        end
+
+        #
+        # The timezone
+        #
+        # @return [String] The timezone in `[+-]hh:mm(:ss)` format (`Z` for UTC)
+        #
+        def zone
+          zoned_date_time.zone.id
+        end
+
+        # @!visibility private
+        def respond_to_missing?(method, _include_private = false)
+          return true if zoned_date_time.respond_to?(method)
+          return true if Time.instance_methods.include?(method.to_sym)
+
+          super
+        end
+
+        #
+        # Forward missing methods to the +ZonedDateTime+ object or a ruby +Time+
+        # object representing the same instant
+        #
+        def method_missing(method, *args, &block)
+          return zoned_date_time.send(method, *args, &block) if zoned_date_time.respond_to?(method)
+          return to_time.send(method, *args, &block) if Time.instance_methods.include?(method.to_sym)
+
+          super
+        end
+
+        # Add other to self
+        #
+        # @param other [java.time.Duration, String, Numeric]
+        #
+        # @return [DateTimeType]
+        def +(other) # rubocop:disable Metrics
+          if other.is_a?(java.time.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))
+          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
+
+        # Subtract other from self
+        #
+        # if other is a Duration-like object, the result is a new
+        # {DateTimeType} of duration seconds earlier in time.
+        #
+        # 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]
+        #
+        # @return [DateTimeType, java.Time.Duration]
+        def -(other) # rubocop:disable Metrics
+          if other.is_a?(java.time.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))
+          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
+      end
+      # rubocop: enable Metrics/ClassLength
+    end
+  end
+end

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require_relative 'comparable_type'
+require_relative 'numeric_type'
+
+module OpenHAB
+  module DSL
+    module Types
+      java_import org.openhab.core.library.types.DecimalType
+
+      #
+      # Add methods to core OpenHAB DecimalType to make it behave as a Ruby
+      # BigDecimal object
+      #
+      #
+      # Any method not explicitly defined is forwarded to the +BigDecimal+
+      # representation of this object.
+      #
+      class DecimalType
+        # @!parse include Type
+        include NumericType
+        include ComparableType
+
+        #
+        # Create a new instance of DateTimeType
+        #
+        # @param value [java.math.BigDecimal, Items::NumericItem, Numeric]
+        def initialize(*args) # rubocop:disable Metrics
+          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)
+          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)
+          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 [Object] other String or Unit representing an OpenHAB 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)
+          QuantityType.new(to_big_decimal, other)
+        end
+
+        #
+        # Comparison
+        #
+        # @param [NumericType, Items::NumericItem, 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) # rubocop:disable Metrics
+          logger.trace("(#{self.class}) #{self} <=> #{other} (#{other.class})")
+          if other.is_a?(QuantityType)
+            (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)
+            lhs, rhs = other.coerce(self)
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Type Coercion
+        #
+        # Coerce object to a DecimalType
+        #
+        # @param [Items::NumericItem, Numeric, Type] other object to
+        #   coerce to a {DecimalType}
+        #
+        #   if +other+ is a {Type}, +self+ will instead be coerced
+        #   to that type to accomodate comparison with things such as {OnOffType}
+        #
+        # @return [[DecimalType, DecimalType]]
+        #
+        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)
+            [self.class.new(other.to_d), self]
+          else
+            raise TypeError, "can't convert #{other.class} into #{self.class}"
+          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))
+                elsif other.is_a?(java.math.BigDecimal)
+                  self.class.new(to_big_decimal.#{java_op}(other))
+                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