openhab-jrubyscripting 5.0.0.rc10 → 5.0.0.rc12

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

@@ -7,15 +7,24 @@ module OpenHAB
     module Java
       java_import java.time.LocalDate
 
-      # Extensions to LocalDate
+      # Extensions to {java.time.LocalDate}
       class LocalDate
         include Time
         include Between
+        include Ephemeris
 
-        class << self # rubocop:disable Lint/EmptyClass
-          # @!attribute [r] now
-          #   @return [ZonedDateTime]
-        end
+        # @!scope class
+
+        # @!attribute [r] now
+        #   @return [LocalDate]
+
+        # @!method parse(text, formatter=nil)
+        #   Converts the given text into a LocalDate.
+        #   @param [String] text The text to parse
+        #   @param [java.time.format.DateTimeFormatter] formatter The formatter to use
+        #   @return [LocalDate]
+
+        # @!scope instance
 
         # @param [TemporalAmount, LocalDate, Numeric] other
         #   If other is a Numeric, it's interpreted as days.
@@ -24,11 +33,11 @@ module OpenHAB
         def -(other)
           case other
           when Date
-            Period.of_days(day_of_year - other.yday)
+            self - other.to_local_date
           when MonthDay
             self - other.at_year(year)
           when LocalDate
-            Period.of_days(day_of_year - other.day_of_year)
+            Period.between(other, self)
           when Duration
             minus_days(other.to_days)
           when Numeric
@@ -66,6 +75,7 @@ module OpenHAB
           Date.new(year, month_value, day_of_month)
         end
 
+        # @return [Month]
         alias_method :to_month, :month
 
         # @return [MonthDay]

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

@@ -7,6 +7,8 @@ module OpenHAB
     module Java
       java_import java.time.LocalTime
 
+      #
+      # Extensions to {java.time.LocalTime}
       #
       # @example
       #   break_time = LocalTime::NOON
@@ -36,15 +38,23 @@ module OpenHAB
         include Between
         # @!parse include Time
 
-        # @!visibility private
         class << self
+          # @!attribute [r] now
+          #   @return [LocalTime]
+
+          # @!visibility private
+          alias_method :raw_parse, :parse
+
           #
-          # Parses strings in the form "h[:mm[:ss]] [am/pm]"
+          # Parses strings in the form "h[:mm[:ss]] [am/pm]" when no formatter is given.
           #
           # @param [String] string
+          # @param [java.time.format.DateTimeFormatter] formatter The formatter to use
           # @return [LocalTime]
           #
-          def parse(string)
+          def parse(string, formatter = nil)
+            return raw_parse(string, formatter) if formatter
+
             format = /(am|pm)$/i.match?(string) ? "h[:mm[:ss][.S]][ ]a" : "H[:mm[:ss][.S]]"
             java_send(:parse, [java.lang.CharSequence, java.time.format.DateTimeFormatter],
                       string, java.time.format.DateTimeFormatterBuilder.new

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

@@ -7,7 +7,7 @@ module OpenHAB
     module Java
       Month = java.time.Month
 
-      # Extensions to Month
+      # Extensions to {java.time.Month}
       class Month
         include Between
         # @!parse include Time

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

@@ -7,9 +7,10 @@ module OpenHAB
     module Java
       java_import java.time.MonthDay
 
-      # Extensions to MonthDay
+      # Extensions to {java.time.MonthDay}
       class MonthDay
         include Between
+        include Ephemeris
 
         class << self
           #
@@ -38,12 +39,22 @@ module OpenHAB
 
         # @return [MonthDay]
         def +(other)
-          (LocalDate.of(1900, month, day_of_month) + other).to_month_day
+          case other
+          when java.time.temporal.TemporalAmount, Numeric
+            (LocalDate.of(1900, month, day_of_month) + other).to_month_day
+          else
+            (to_local_date(other.to_local_date) + other).to_month_day
+          end
         end
 
         # @return [MonthDay, Period]
         def -(other)
-          d = (LocalDate.of(1900, month, day_of_month) - other)
+          d = case other
+              when java.time.temporal.TemporalAmount, Numeric
+                LocalDate.of(1900, month, day_of_month) - other
+              else
+                to_local_date(other.to_local_date) - other
+              end
           return d if d.is_a?(java.time.Period)
 
           d.to_month_day
@@ -76,6 +87,7 @@ module OpenHAB
           year.at_month_day(self)
         end
 
+        # @return [Month]
         alias_method :to_month, :month
 
         # @param [Date, nil] context

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

@@ -5,7 +5,7 @@ module OpenHAB
     module Java
       java_import java.time.Period
 
-      # Extensions to Period
+      # Extensions to {java.time.Period}
       class Period
         # @!parse include TemporalAmount
 

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

@@ -5,7 +5,7 @@ module OpenHAB
     module Java
       java_import java.time.temporal.TemporalAmount
 
-      # Extensions to TemporalAmount
+      # Extensions to {java.time.temporal.TemporalAmount}
       module TemporalAmount
         # Subtract `self` to {ZonedDateTime.now}
         # @return [ZonedDateTime]

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

@@ -50,7 +50,11 @@ module OpenHAB
         # Convert `other` to this class, if possible
         # @return [Array, nil]
         def coerce(other)
-          [other.send(self.class.coercion_method), self] if other.respond_to?(self.class.coercion_method)
+          coercion_method = self.class.coercion_method
+          return unless other.respond_to?(coercion_method)
+          return [other.send(coercion_method), self] if other.method(coercion_method).arity.zero?
+
+          [other.send(coercion_method, self), self]
         end
       end
     end

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

@@ -7,17 +7,33 @@ module OpenHAB
     module Java
       ZonedDateTime = java.time.ZonedDateTime
 
-      # Extensions to 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
 
-        alias_method :to_local_time, :toLocalTime
+        # @return [Month]
         alias_method :to_month, :month
 
         # @param [TemporalAmount, #to_zoned_date_time, Numeric] other
@@ -87,6 +103,88 @@ module OpenHAB
           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

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

@@ -5,6 +5,7 @@ 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}
@@ -84,11 +85,12 @@ class Date
   #
   def coerce(other)
     return nil unless other.respond_to?(:to_date)
-    return [other.to_date(self), self] if other.method(:to_date).arity == 1
+    return [other.to_date, self] if other.method(:to_date).arity.zero?
 
-    [other.to_date, self]
+    [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

@@ -11,6 +11,7 @@ require "forwardable"
 class DateTime < Date
   extend Forwardable
   include OpenHAB::CoreExt::Between
+  include OpenHAB::CoreExt::Ephemeris
 
   # (see Time#plus_with_temporal)
   def plus_with_temporal(other)

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

@@ -151,7 +151,12 @@ module OpenHAB
         # @return [QuantityType] `self` as a {QuantityType} of the supplied Unit
         #
         def |(unit) # rubocop:disable Naming/BinaryOperatorParameterName
-          unit = org.openhab.core.types.util.UnitUtils.parse_unit(unit.to_str) if unit.respond_to?(:to_str)
+          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)
 

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

@@ -6,6 +6,7 @@ require "forwardable"
 class Time
   extend Forwardable
   include OpenHAB::CoreExt::Between
+  include OpenHAB::CoreExt::Ephemeris
 
   #
   # @!method +(other)

data/lib/openhab/dsl/debouncer.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Provides the feature for debouncing calls to a given block.
+    #
+    # The debouncer can filter events and only allow the events on the leading or trailing edge
+    # of the given interval. Its behavior can be customized through settings passed to its
+    # {initialize constructor}.
+    #
+    # The following timing diagram illustrates the incoming triggers and the actual executions
+    # using various options.
+    #
+    # ```ruby
+    #                              1    1    2    2    3    3    4    4
+    #                    0    5    0    5    0    5    0    5    0    5
+    # Triggers        : 'X.X...X...X..XX.X.X......XXXXXXXXXXX....X.....'
+    # leading: false
+    # for:5           : '|....X|....X |....X      |....X|....X   |....X'
+    # leading: true
+    # for:5           : 'X.....X......X....X......X....X....X....X.....'
+    #
+    # more options, leading: false
+    # Triggers        : 'X.X...X...X..XX.X.X......XXXXXXXXXXX....X.....'
+    # for:5 idle:3    : '|....X|......X|......X...|............X.|....X'
+    # for:5 idle:5    : '|......................X.|..............X.....'
+    # for:5..5 idle:X : '|....X|....X.|....X......|....X|....X...|....X'
+    # for:5..6 idle:5 : '|.....X...|.....X.|....X.|.....X|.....X.|....X'
+    # for:5..7 idle:5 : '|......X..|......X|....X.|......X|......X.....'
+    # for:5..8 idle:5 : '|.......X.|.......X......|.......X|.....X.....'
+    # for:5..8 idle:3 : '|....X|......X|......X...|.......X|....X|....X'
+    # for:5..8 idle:2 : '|....X|.....X|......X....|.......X|....X|....X'
+    # ```
+    #
+    # Notes:
+    # - `|` indicates the start of the debounce period
+    # - With `for: 5..5` (a range with begin=end), the `idle_time` argument is irrelevant
+    #   and be unset/set to any value as it will not alter the debouncer's behavior.
+    # - Without an `idle_time`, the range end in `for: X..Y` is irrelevant. It is equivalent to
+    #   `for: X` without the end of the range.
+    #
+    class Debouncer
+      # @return [Range,nil] The range of accepted debounce period, or nil if debouncing is disabled.
+      attr_reader :interval
+
+      # @return [Duration, nil] The minimum idle time to stop debouncing.
+      attr_reader :idle_time
+
+      #
+      # Constructor to create a debouncer object.
+      #
+      # The constructor sets the options and behaviour of the debouncer when the {#call}
+      # method is called.
+      #
+      # Terminology:
+      # - `calls` are invocations of the {#call} method, i.e. the events that need to be throttled / debounced.
+      # - `executions` are the actual code executions of the given block. Executions usually occur
+      #   less frequently than the call to the debounce method.
+      #
+      # @param [Duration,Range,nil] for The minimum and optional maximum execution interval.
+      #   - {Duration}: The minimum interval between executions. The debouncer will not execute
+      #     the given block more often than this.
+      #   - {Range}: A range of {Duration}s for the minimum to maximum interval between executions.
+      #     The range end defines the maximum duration from the initial trigger, at which
+      #     the debouncer will execute the block, even when an `idle_time` argument was given and
+      #     calls continue to occur at an interval less than `idle_time`.
+      #   - `nil`: When `nil`, no debouncing is performed, all the other parameters are ignored,
+      #     and every call will result in immediate execution of the given block.
+      #
+      # @param [true,false] leading
+      #   - `true`: Perform leading edge "debouncing". Execute the first call then ignore
+      #     subsequent calls that occur within the debounce period.
+      #   - `false`: Perform trailing edge debouncing. Execute the last call at the end of
+      #     the debounce period and ignore all the calls leading up to it.
+      #
+      # @param [Duration,nil] idle_time The minimum idle time between calls to stop debouncing.
+      #   The debouncer will continue to hold until the interval between two calls is longer
+      #   than the idle time or until the maximum interval between executions, when
+      #   specified, is reached.
+      #
+      # @return [void]
+      #
+      def initialize(for:, leading: false, idle_time: nil)
+        @interval = binding.local_variable_get(:for)
+        return unless @interval
+
+        @interval = (@interval..) unless @interval.is_a?(Range)
+
+        @leading = leading
+        @idle_time = idle_time
+        @mutex = Mutex.new
+        @block = nil
+        @timer = nil
+        reset
+      end
+
+      #
+      # Debounces calls to the given block.
+      #
+      # This method is meant to be called repeatedly with the same given block.
+      # However, if no block is given, it will call and debounce the previously given block
+      #
+      # @yield Block to be debounced
+      #
+      # @return [void]
+      #
+      # @example Basic trailing edge debouncing
+      #   debouncer = Debouncer.new(for: 1.minute)
+      #   (1..100).each do
+      #     debouncer.call { logger.info "I won't log more often than once a minute" }
+      #     sleep 20 # call the debouncer every 20 seconds
+      #   end
+      #
+      # @example Call the previous debounced block
+      #   debouncer = Debouncer.new(for: 1.minute)
+      #   debouncer.call { logger.info "Hello. It is #{Time.now}" } # First call to debounce
+      #
+      #   after(20.seconds) do |timer|
+      #     debouncer.call # Call the original block above
+      #     timer.reschedule unless timer.cancelled?
+      #   end
+      #
+      def call(&block)
+        @block = block if block
+        raise ArgumentError, "No block has been provided" unless @block
+
+        return call! unless @interval # passthrough mode, no debouncing when @interval is nil
+
+        now = ZonedDateTime.now
+        if leading?
+          leading_edge_debounce(now)
+        else
+          trailing_edge_debounce(now)
+        end
+        @mutex.synchronize { @last_timestamp = now }
+      end
+
+      #
+      # Executes the latest block passed to the {#debounce} call regardless of any debounce settings.
+      #
+      # @return [Object] The return value of the block
+      #
+      def call!
+        @block.call
+      end
+
+      #
+      # Resets the debounce period and cancels any outstanding block executions of a trailing edge debouncer.
+      #
+      # - A leading edge debouncer will execute its block on the next call and start a new debounce period.
+      # - A trailing edge debouncer will reset its debounce timer and the next call will become the start
+      #   of a new debounce period.
+      #
+      # @return [Boolean] True if a pending execution was cancelled.
+      #
+      def reset
+        @mutex.synchronize do
+          @last_timestamp = @leading_timestamp = @interval.begin.ago - 1.second if leading?
+          @timer&.cancel
+        end
+      end
+
+      #
+      # Immediately executes any outstanding event of a trailing edge debounce.
+      # The next call will start a new period.
+      #
+      # It has no effect on a leading edge debouncer - use {#reset} instead.
+      #
+      # @return [Boolean] True if an existing debounce timer was rescheduled to run immediately.
+      #   False if there were no outstanding executions.
+      #
+      def flush
+        @mutex.synchronize do
+          if @timer&.cancel
+            call!
+            true
+          end
+        end
+      end
+
+      #
+      # Returns true to indicate that this is a leading edge debouncer.
+      #
+      # @return [true,false] True if this object was created to be a leading edge debouncer. False otherwise.
+      #
+      def leading?
+        @leading
+      end
+
+      private
+
+      def too_soon?(now)
+        now < @leading_timestamp + @interval.begin
+      end
+
+      # @return [true,false] When max interval is not set/required, always returns false,
+      #   because there is no maximum interval requirement.
+      #   When it is set, return true if the max interval condition is met, or false otherwise
+      def max_interval?(now)
+        @interval.end && now >= @leading_timestamp + @interval.end
+      end
+
+      # @return [true,false] When idle_time is not set/required, always returns true,
+      #   as if the idle time condition is met.
+      #   When it is set, return true if the idle time condition is met, or false otherwise
+      def idle?(now)
+        @idle_time.nil? || now >= @last_timestamp + @idle_time
+      end
+
+      def leading_edge_debounce(now)
+        @mutex.synchronize do
+          next if too_soon?(now)
+          next unless idle?(now) || max_interval?(now)
+
+          @leading_timestamp = now
+          call!
+        end
+      end
+
+      def start_timer(now)
+        @leading_timestamp = now
+        @timer = DSL.after(@interval.begin) { @mutex.synchronize { call! } }
+      end
+
+      def handle_leading_event(now)
+        @leading_timestamp = now
+        @initial_wait ||= [@interval.begin, @idle_time].compact.max
+        @timer.reschedule(@initial_wait)
+      end
+
+      def handle_intermediate_event(now)
+        execution_time = @leading_timestamp + @interval.begin
+
+        execution_time = [execution_time, now + @idle_time].max if @idle_time && (@last_timestamp + @idle_time != now)
+        if @interval.end
+          max_execution_time = @leading_timestamp + @interval.end
+          execution_time = max_execution_time if max_execution_time < execution_time
+        end
+
+        if execution_time <= now
+          @timer.cancel
+          call!
+        elsif execution_time > @timer.execution_time
+          @timer.reschedule(execution_time)
+        end
+      end
+
+      def trailing_edge_debounce(now)
+        @mutex.synchronize do
+          next start_timer(now) unless @timer
+          next handle_intermediate_event(now) if @timer.active?
+
+          handle_leading_event(now)
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/items/builder.rb

@@ -97,8 +97,10 @@ module OpenHAB
         def item(*args, **kwargs, &block)
           item = ItemBuilder.new(*args, provider: provider, **kwargs)
           item.instance_eval(&block) if block
-          provider.add(item)
-          Core::Items::Proxy.new(item)
+          r = provider.add(item)
+          return Core::Items::Proxy.new(r) if r.is_a?(Item)
+
+          item
         end
       end
 
@@ -185,6 +187,30 @@ module OpenHAB
           def item_factory
             @item_factory ||= org.openhab.core.library.CoreItemFactory.new
           end
+
+          #
+          # Convert the given array to an array of strings.
+          # Convert Semantics classes to their simple name.
+          #
+          # @param [String,Symbol,Semantics::Tag] tags A list of strings, symbols, or Semantics classes
+          # @return [Array] An array of strings
+          #
+          # @example
+          #   tags = normalize_tags("tag1", Semantics::LivingRoom)
+          #
+          # @!visibility private
+          def normalize_tags(*tags)
+            semantics = proc { |tag| tag.respond_to?(:java_class) && tag < Semantics::Tag }
+
+            tags.compact.map do |tag|
+              case tag
+              when String then tag
+              when Symbol then tag.to_s
+              when semantics then tag.java_class.simple_name
+              else raise ArgumentError, "`#{tag}` must be a subclass of Semantics::Tag, a `Symbol`, or a `String`."
+              end
+            end
+          end
         end
 
         # @param dimension [Symbol, nil] The unit dimension for a {NumberItem} (see {ItemBuilder#dimension})
@@ -292,18 +318,7 @@ module OpenHAB
         # @return [void]
         #
         def tag(*tags)
-          unless tags.all? do |tag|
-                   tag.is_a?(String) ||
-                   tag.is_a?(Symbol) ||
-                   (tag.is_a?(Module) && tag < Semantics::Tag)
-                 end
-            raise ArgumentError, "`tag` must be a subclass of Semantics::Tag, or a `String``."
-          end
-
-          tags.each do |tag|
-            tag = tag.name.split("::").last if tag.is_a?(Module) && tag < Semantics::Tag
-            @tags << tag.to_s
-          end
+          @tags += self.class.normalize_tags(*tags)
         end
 
         #