openhab-scripting 4.46.2 → 5.0.0

data/lib/openhab/core_ext/java/zoned_date_time.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "time"
+
+module OpenHAB
+  module CoreExt
+    module Java
+      ZonedDateTime = java.time.ZonedDateTime
+
+      # Extensions to {java.time.ZonedDateTime}
+      class ZonedDateTime
+        include Time
+        include Between
+
+        class << self # rubocop:disable Lint/EmptyClass
+          # @!scope class
+
+          # @!attribute [r] now
+          #   @return [ZonedDateTime]
+
+          # @!method parse(text, formatter = nil)
+          #   Parses a string into a ZonedDateTime object.
+          #
+          #   @param [String] text The text to parse.
+          #   @param [java.time.format.DateTimeFormatter] formatter The formatter to use.
+          #   @return [ZonedDateTime]
+        end
+
+        # @!scope instance
+
+        # @return [LocalTime]
+        def to_local_time(_context = nil)
+          toLocalTime
+        end
+
+        # @return [Month]
+        alias_method :to_month, :month
+
+        # @param [TemporalAmount, #to_zoned_date_time, Numeric] other
+        #   If other is a Numeric, it's interpreted as seconds.
+        # @return [Duration] If other responds to #to_zoned_date_time
+        # @return [ZonedDateTime] If other is a TemporalAmount
+        def -(other)
+          if other.respond_to?(:to_zoned_date_time)
+            java.time.Duration.between(other.to_zoned_date_time, self)
+          elsif other.is_a?(Numeric)
+            minus(other.seconds)
+          else
+            minus(other)
+          end
+        end
+
+        # @param [TemporalAmount, Numeric] other
+        #   If other is a Numeric, it's interpreted as seconds.
+        # @return [ZonedDateTime]
+        def +(other)
+          return plus(other.seconds) if other.is_a?(Numeric)
+
+          plus(other)
+        end
+
+        #
+        # The number of seconds since the Unix epoch.
+        #
+        # @return [Integer]
+        def to_i
+          to_instant.epoch_second
+        end
+
+        #
+        # The number of seconds since the Unix epoch.
+        #
+        # @return [Float]
+        def to_f
+          to_instant.to_epoch_milli / 1000.0
+        end
+
+        # @return [Date]
+        def to_date
+          Date.new(year, month_value, day_of_month)
+        end
+
+        # @return [LocalDate]
+        def to_local_date(_context = nil)
+          toLocalDate
+        end
+
+        # @return [MonthDay]
+        def to_month_day
+          MonthDay.of(month, day_of_month)
+        end
+
+        # This comes from JRuby
+
+        # @!method to_time
+        #   @return [Time]
+
+        # @param [ZonedDateTime, nil] context
+        #   A {ZonedDateTime} used to fill in missing fields
+        #   during conversion. Not used in this class.
+        # @return [self]
+        def to_zoned_date_time(context = nil) # rubocop:disable Lint/UnusedMethodArgument
+          self
+        end
+
+        # @group Ephemeris Methods
+        #   (see CoreExt::Ephemeris)
+
+        #
+        # Name of the holiday for this date.
+        #
+        # @param [String, nil] holiday_file Optional path to XML file to use for holiday definitions.
+        # @return [Symbol, nil]
+        #
+        # @example
+        #   MonthDay.parse("12-25").holiday # => :christmas
+        #
+        def holiday(holiday_file = nil)
+          ::Ephemeris.get_bank_holiday_name(*[self, holiday_file || DSL.holiday_file].compact)&.downcase&.to_sym
+        end
+
+        #
+        # Determines if this date is on a holiday.
+        #
+        # @param [String, nil] holiday_file Optional path to XML file to use for holiday definitions.
+        # @return [true, false]
+        #
+        def holiday?(holiday_file = nil)
+          ::Ephemeris.bank_holiday?(*[self, holiday_file || DSL.holiday_file].compact)
+        end
+
+        #
+        # Name of the closest holiday on or after this date.
+        #
+        # @param [String, nil] holiday_file Optional path to XML file to use for holiday definitions.
+        # @return [Symbol]
+        #
+        def next_holiday(holiday_file = nil)
+          ::Ephemeris.get_next_bank_holiday(*[self, holiday_file || DSL.holiday_file].compact).downcase.to_sym
+        end
+
+        #
+        # Determines if this time is during a weekend.
+        #
+        # @return [true, false]
+        #
+        # @example
+        #   Time.now.weekend?
+        #
+        def weekend?
+          ::Ephemeris.weekend?(self)
+        end
+
+        #
+        # Determines if this time is during a specific dayset
+        #
+        # @param [String, Symbol] set
+        # @return [true, false]
+        #
+        # @example
+        #   Time.now.in_dayset?("school")
+        #
+        def in_dayset?(set)
+          ::Ephemeris.in_dayset?(set.to_s, self)
+        end
+
+        #
+        # Calculate the number of days until a specific holiday
+        #
+        # @param [String, Symbol] holiday
+        # @param [String, nil] holiday_file Optional path to XML file to use for holiday definitions.
+        # @return [Integer]
+        # @raise [ArgumentError] if the holiday isn't valid
+        #
+        # @example
+        #   Time.now.days_until(:christmas) # => 2
+        #
+        def days_until(holiday, holiday_file = nil)
+          holiday = holiday.to_s.upcase
+          r = ::Ephemeris.get_days_until(*[self, holiday, holiday_file || DSL.holiday_file].compact)
+          raise ArgumentError, "#{holiday.inspect} isn't a recognized holiday" if r == -1
+
+          r
+        end
+
+        # @endgroup
+
+        # @return [Integer, nil]
+        def <=>(other)
+          # compare instants, otherwise it will differ by timezone, which we don't want
+          # (use eql? if you care about that)
+          if other.respond_to?(:to_zoned_date_time)
+            to_instant.compare_to(other.to_zoned_date_time(self).to_instant)
+          elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(self))
+            lhs <=> rhs
+          end
+        end
+
+        #
+        # Converts `other` to {ZonedDateTime}, if possible
+        #
+        # @param [#to_zoned_date_time] other
+        # @return [Array, nil]
+        #
+        def coerce(other)
+          [other.to_zoned_date_time(self), self] if other.respond_to?(:to_zoned_date_time)
+        end
+      end
+    end
+  end
+end
+
+# @!parse ZonedDateTime = OpenHAB::CoreExt::Java::ZonedDateTime

data/lib/openhab/core_ext/ruby/array.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Extensions to Array
+class Array
+  #
+  # Ensure an object is an array, by wrapping
+  # it in an array if it's not already an array.
+  # @return [Array]
+  #
+  # @see https://github.com/rails/rails/blob/main/activesupport/lib/active_support/core_ext/array/wrap.rb
+  #
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary
+    else
+      [object]
+    end
+  end
+end

data/lib/openhab/core_ext/ruby/date.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "date"
+
+# Extensions to Date
+class Date
+  include OpenHAB::CoreExt::Between
+  include OpenHAB::CoreExt::Ephemeris
+
+  #
+  # Extends {#+} to allow adding a {java.time.temporal.TemporalAmount TemporalAmount}
+  #
+  # @param [java.time.temporal.TemporalAmount] other
+  # @return [LocalDate] If other is a {java.time.temporal.TemporalAmount TemporalAmount}
+  #
+  def plus_with_temporal(other)
+    return to_local_date + other if other.is_a?(java.time.temporal.TemporalAmount)
+
+    plus_without_temporal(other)
+  end
+  alias_method :plus_without_temporal, :+
+  alias_method :+, :plus_with_temporal
+
+  #
+  # Extends {#-} to allow subtracting a {java.time.temporal.TemporalAmount TemporalAmount}
+  #
+  # @param [java.time.temporal.TemporalAmount] other
+  # @return [LocalDate] If other is a {java.time.temporal.TemporalAmount TemporalAmount}
+  #
+  def minus_with_temporal(other)
+    case other
+    when java.time.temporal.TemporalAmount, java.time.LocalDate
+      to_local_date - other
+    else
+      minus_without_temporal(other)
+    end
+  end
+  alias_method :minus_without_temporal, :-
+  alias_method :-, :minus_with_temporal
+
+  # @return [LocalDate]
+  def to_local_date(_context = nil)
+    java.time.LocalDate.of(year, month, day)
+  end
+
+  # @return [Month]
+  def to_month
+    java.time.Month.of(month)
+  end
+
+  # @return [MonthDay]
+  def to_month_day
+    java.time.MonthDay.of(month, day)
+  end
+
+  # @param [ZonedDateTime, nil] context
+  #   A {ZonedDateTime} used to fill in missing fields during conversion.
+  #   {OpenHAB::CoreExt::Java::ZonedDateTime.now ZonedDateTime.now} is assumed
+  #   if not given.
+  # @return [ZonedDateTime]
+  def to_zoned_date_time(context = nil)
+    to_local_date.to_zoned_date_time(context)
+  end
+
+  # @return [Integer, nil]
+  def compare_with_coercion(other)
+    return compare_without_coercion(other) if other.is_a?(self.class)
+
+    return self <=> other.to_date(self) if other.is_a?(java.time.MonthDay)
+
+    if other.respond_to?(:coerce) && (lhs, rhs = other.coerce(self))
+      return lhs <=> rhs
+    end
+
+    compare_without_coercion(other)
+  end
+  alias_method :compare_without_coercion, :<=>
+  alias_method :<=>, :compare_with_coercion
+
+  #
+  # Convert `other` to Date, if possible.
+  #
+  # @param [#to_date] other
+  # @return [Array, nil]
+  #
+  def coerce(other)
+    return nil unless other.respond_to?(:to_date)
+    return [other.to_date, self] if other.method(:to_date).arity.zero?
+
+    [other.to_date(self), self]
+  end
+
+  remove_method :inspect
+  # @return [String]
+  alias_method :inspect, :to_s
+end

data/lib/openhab/core_ext/ruby/date_time.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "date"
+require "forwardable"
+
+# DateTime inherits from Date, but is more similar to Time semantically.
+# So it avoid alias_method chain bombs, and to ensure the correct end methods
+# exist here, we define the important methods from Time here as well.
+
+# Extensions to DateTime
+class DateTime < Date
+  extend Forwardable
+  include OpenHAB::CoreExt::Between
+  include OpenHAB::CoreExt::Ephemeris
+
+  # (see Time#plus_with_temporal)
+  def plus_with_temporal(other)
+    return to_zoned_date_time + other if other.is_a?(java.time.temporal.TemporalAmount)
+
+    plus_without_temporal(other)
+  end
+  # alias_method :plus_without_temporal, :+ # already done by Date
+  alias_method :+, :plus_with_temporal
+
+  # (see Time#minus_with_temporal)
+  def minus_with_temporal(other)
+    return to_zoned_date_time - other if other.is_a?(java.time.temporal.TemporalAmount)
+
+    # Exclude subtracting against the same class
+    if other.respond_to?(:to_zoned_date_time) && !other.is_a?(self.class)
+      return to_zoned_date_time - other.to_zoned_date_time
+    end
+
+    minus_without_temporal(other)
+  end
+  # alias_method :minus_without_temporal, :- # already done by Date
+  alias_method :-, :minus_with_temporal
+
+  # @!method to_local_time
+  #   @return [LocalTime]
+  def_delegator :to_zoned_date_time, :to_local_time
+
+  # (see Time#to_zoned_date_time)
+  def to_zoned_date_time(context = nil) # rubocop:disable Lint/UnusedMethodArgument
+    to_java(ZonedDateTime)
+  end
+
+  # (see Time#coerce)
+  def coerce(other)
+    return unless other.respond_to?(:to_zoned_date_time)
+
+    zdt = to_zoned_date_time
+    [other.to_zoned_date_time(zdt), zdt]
+  end
+end

data/lib/openhab/core_ext/ruby/module.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Extensions to Module
+class Module
+  #
+  # Returns the name of the class or module, without any containing module or package.
+  #
+  # @return [String, nil]
+  #
+  def simple_name
+    return unless name
+
+    @simple_name ||= java_class&.simple_name || name.split("::").last
+  end
+end

data/lib/openhab/core_ext/ruby/numeric.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# Extensions to Integer
+class Integer
+  class << self
+    #
+    # @!macro def_duration_method
+    #   @!method $1
+    #
+    #   Create {Duration} of `self` $1
+    #
+    #   @return [Duration]
+    #
+    # @!visibility private
+    def def_duration_method(unit)
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{unit}                            # def seconds
+          java.time.Duration.of_#{unit}(self)  #   java.time.Duration.of_seconds(self)
+        end                                    # end
+      RUBY
+    end
+
+    #
+    # @!macro def_period_method
+    #   @!method $1
+    #
+    #   Create {Period} of `self` $1
+    #
+    #   @return [Period]
+    #
+    # @!visibility private
+    def def_period_method(unit)
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{unit}                          # def days
+          java.time.Period.of_#{unit}(self)  #   java.time.Period.of_days(self)
+        end                                  # end
+      RUBY
+    end
+  end
+
+  #
+  # Create {Duration} of `self` milliseconds
+  #
+  # @return [Duration]
+  #
+  def milliseconds
+    Duration.of_millis(self)
+  end
+  alias_method :millisecond, :milliseconds
+  alias_method :ms, :milliseconds
+  def_duration_method(:seconds)
+  alias_method :second, :seconds
+  def_duration_method(:minutes)
+  alias_method :minute, :minutes
+  def_duration_method(:hours)
+  alias_method :hour, :hours
+  def_period_method(:days)
+  alias_method :day, :days
+  def_period_method(:months)
+  alias_method :month, :months
+  def_period_method(:years)
+  alias_method :year, :years
+end
+
+# Extensions to Float
+class Float
+  #
+  # Create {Duration} of `self` milliseconds
+  #
+  # @return [Duration]
+  #
+  def milliseconds
+    java.time.Duration.of_nanos((self * 1_000_000).to_i)
+  end
+  alias_method :millisecond, :milliseconds
+  alias_method :ms, :milliseconds
+
+  #
+  # Create {Duration} of `self` seconds
+  #
+  # @return [Duration]
+  #
+  def seconds
+    (self * 1000).milliseconds
+  end
+  alias_method :second, :seconds
+
+  #
+  # Create {Duration} of `self` minutes
+  #
+  # @return [Duration]
+  #
+  def minutes
+    (self * 60).seconds
+  end
+  alias_method :minute, :minutes
+
+  #
+  # Create {Duration} of `self` hours
+  #
+  # @return [Duration]
+  #
+  def hours
+    (self * 60).minutes
+  end
+  alias_method :hour, :hours
+
+  #
+  # Create {Duration} of `self` days
+  #
+  # @return [Duration]
+  #
+  def days
+    (self * 24).hours
+  end
+  alias_method :day, :days
+
+  #
+  # Create {Duration} of `self` months
+  #
+  # @return [Duration]
+  #
+  def months
+    (self * java.time.temporal.ChronoUnit::MONTHS.duration.to_i).seconds
+  end
+  alias_method :month, :months
+
+  #
+  # Create {Duration} of `self` years
+  #
+  # @return [Duration]
+  #
+  def years
+    (self * java.time.temporal.ChronoUnit::YEARS.duration.to_i).seconds
+  end
+  alias_method :year, :years
+end
+
+module OpenHAB
+  module CoreExt
+    module Ruby
+      #
+      # Extend Numeric to create quantity object
+      #
+      module QuantityTypeConversion
+        #
+        # Convert Numeric to a QuantityType
+        #
+        # @param [String, javax.measure.Unit] unit
+        #
+        # @return [QuantityType] `self` as a {QuantityType} of the supplied Unit
+        #
+        def |(unit) # rubocop:disable Naming/BinaryOperatorParameterName
+          if unit.respond_to?(:to_str)
+            parsed_unit = org.openhab.core.types.util.UnitUtils.parse_unit(unit.to_str)
+            raise ArgumentError, "Unknown unit #{unit}" unless parsed_unit
+
+            unit = parsed_unit
+          end
+
+          return super unless unit.is_a?(javax.measure.Unit)
+
+          Core::Types::QuantityType.new(to_d.to_java, unit)
+        end
+      end
+
+      # Extensions to Numeric
+      module Numeric
+        include QuantityTypeConversion
+        # non-Integer/Float (i.e. BigDecimal) can still be converted to Duration, via converting to float first
+        extend Forwardable
+        def_delegators :to_f,
+                       :milliseconds,
+                       :millisecond,
+                       :ms,
+                       :seconds,
+                       :second,
+                       :minutes,
+                       :minute,
+                       :hours,
+                       :hour,
+                       :day,
+                       :days,
+                       :month,
+                       :months,
+                       :year,
+                       :years
+      end
+
+      # Integer already has #|, so we have to prepend it here
+      ::Integer.prepend(QuantityTypeConversion)
+      ::Numeric.include(Numeric)
+    end
+  end
+end

data/lib/openhab/core_ext/ruby/range.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    module Ruby
+      # Extensions to Range
+      module Range
+        def cover?(object)
+          # inverted circular range
+          if circular?
+            return object >= self.begin || object < self.end if exclude_end?
+
+            return object >= self.begin || object <= self.end
+          end
+          super
+        end
+
+        # Delegates to {#cover?} if {#circular?}
+        # @!visibility private
+        def ===(object)
+          return cover?(object) if circular?
+
+          super
+        end
+
+        # normal Range#each will not yield at all if begin > end
+        def each
+          return super unless circular?
+          return to_enum(:each) unless block_given?
+
+          val = self.begin
+          loop do
+            is_end = val == self.end
+            break if is_end && exclude_end?
+
+            yield val
+            break if is_end
+
+            val = val.succ
+          end
+        end
+
+        #
+        # Checks if this range is circular
+        #
+        # A circular range is one whose data type will repeat if keep you keep
+        # calling #succ on it, and whose beginning is after its end.
+        #
+        # Used by {#cover?} to check if the value is between `end` and `begin`,
+        # instead of `begin` and `end`.
+        #
+        # @return [true, false]
+        #
+        def circular?
+          return false if self.begin.nil? || self.end.nil?
+          return false if self.begin <= self.end
+
+          case self.begin || self.end
+          when java.time.LocalTime, java.time.MonthDay, java.time.Month
+            true
+          else
+            false
+          end
+        end
+
+        ::Range.prepend(self)
+      end
+    end
+  end
+end

data/lib/openhab/core_ext/ruby/symbol.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Extensions to Symbol
+class Symbol
+  # Ruby 3.0 already has #name
+  alias_method :name, :to_s unless instance_methods.include?(:name)
+end