openhab-jrubyscripting 5.0.0.rc10 → 5.0.0.rc11

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

@@ -21,11 +21,11 @@ module OpenHAB
         #   Undef State
 
         # @!method null?
-        #   Check if `self == NULL`
+        #   Check if `self` == {NULL}
         #   @return [true,false]
 
         # @!method undef?
-        #   Check if `self == UNDEF`
+        #   Check if `self` == {UNDEF}
         #   @return [true,false]
       end
     end

data/lib/openhab/core/value_cache.rb

@@ -26,7 +26,7 @@ module OpenHAB
     #
     # @note Only the {OpenHAB::DSL.shared_cache sharedCache} is exposed in Ruby.
     #   For a private cache, simply use an instance variable. See
-    #   {file:docs/ruby-basics.md#Variables Instance Variables}.
+    #   {file:docs/ruby-basics.md#variables Instance Variables}.
     #
     # @note Because every script or UI rule gets it own JRuby engine instance,
     #   you cannot rely on being able to access Ruby objects between them. Only

data/lib/openhab/core_ext/ephemeris.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    #
+    # Forwards ephemeris helper methods to `#to_zoned_date_time` provided by
+    # the mixed-in class.
+    #
+    # @note openHAB's built-in holiday definitions are based on _bank_
+    #   holidays, so may give some unexpected results. For example, 2022-12-25
+    #   is _not_ Christmas in England because it lands on a Sunday that year,
+    #   so Christmas is considered to be 2022-12-26. See
+    #   [the source](https://github.com/svendiedrichsen/jollyday/tree/master/src/main/resources/holidays)
+    #   for exact definitions. You can always provide your own holiday
+    #   definitions with {OpenHAB::DSL.holiday_file holiday_file} or
+    #   {OpenHAB::DSL.holiday_file! holiday_file!}.
+    #
+    # @see https://www.openhab.org/docs/configuration/actions.html#ephemeris Ephemeris Action
+    # @see Core::Actions::Ephemeris.holiday_name Ephemeris.holiday_name
+    #
+    module Ephemeris
+      # (see Java::ZonedDateTime#holiday)
+      def holiday(holiday_file = nil)
+        to_zoned_date_time.holiday(holiday_file)
+      end
+
+      # (see Java::ZonedDateTime#holiday?)
+      def holiday?(holiday_file = nil)
+        to_zoned_date_time.holiday?(holiday_file)
+      end
+
+      # (see Java::ZonedDateTime#next_holiday)
+      def next_holiday(holiday_file = nil)
+        to_zoned_date_time.next_holiday(holiday_file)
+      end
+
+      # (see Java::ZonedDateTime#weekend?)
+      def weekend?
+        to_zoned_date_time.weekend?
+      end
+
+      # (see Java::ZonedDateTime#in_dayset?)
+      def in_dayset?(set)
+        to_zoned_date_time.in_dayset?(set)
+      end
+
+      # (see Java::ZonedDateTime#days_until)
+      def days_until(holiday, holiday_file = nil)
+        to_zoned_date_time.days_until(holiday, holiday_file)
+      end
+    end
+  end
+end

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

@@ -21,7 +21,7 @@ module OpenHAB
         #
         # `self`, all superclasses and interfaces, recursively.
         #
-        # @return [Array<java.reflect.Type>]
+        # @return [Array<java.lang.reflect.Type>]
         #
         def generic_ancestors
           ancestors.flat_map do |klass|

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

@@ -5,13 +5,37 @@ module OpenHAB
     module Java
       Duration = java.time.Duration
 
-      # Extensions to Duration
+      # Extensions to {java.time.Duration Java Duration}
       class Duration
         include Between
         # @!parse include TemporalAmount
 
+        #
+        # Convert to integer number of seconds
+        #
+        # @return [Integer]
+        #
         alias_method :to_i, :seconds
 
+        #
+        # @!method zero?
+        #   @return [true,false] Returns true if the duration is zero length.
+        #
+
+        #
+        # @!method negative?
+        #   @return [true,false] Returns true if the duration is less than zero.
+        #
+
+        unless instance_methods.include?(:positive?)
+          #
+          # @return [true, false] Returns true if the duration is greater than zero.
+          #
+          def positive?
+            self > 0 # rubocop:disable Style/NumericPredicate
+          end
+        end
+
         #
         # Convert to number of seconds
         #

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

@@ -11,6 +11,7 @@ module OpenHAB
       class LocalDate
         include Time
         include Between
+        include Ephemeris
 
         class << self # rubocop:disable Lint/EmptyClass
           # @!attribute [r] now
@@ -66,6 +67,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/month_day.rb

@@ -10,6 +10,7 @@ module OpenHAB
       # Extensions to MonthDay
       class MonthDay
         include Between
+        include Ephemeris
 
         class << self
           #
@@ -76,6 +77,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/zoned_date_time.rb

@@ -17,7 +17,10 @@ module OpenHAB
           #   @return [ZonedDateTime]
         end
 
+        # @return [LocalTime]
         alias_method :to_local_time, :toLocalTime
+
+        # @return [Month]
         alias_method :to_month, :month
 
         # @param [TemporalAmount, #to_zoned_date_time, Numeric] other
@@ -87,6 +90,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}
@@ -90,5 +91,6 @@ class Date
   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/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
 

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

@@ -17,10 +17,17 @@ module OpenHAB
       # command. This is available on both the 'command' method and any
       # command-specific methods, e.g. {SwitchItem#on}.
       #
-      # Any update to the timed command state will result in the timer being
-      # cancelled. For example, if you have a Switch on a timer and another
-      # rule sends OFF or ON to that item the timer will be automatically
-      # canceled. Sending a different duration (for:) value for the timed
+      # The timer will be cancelled, and the item's state will not be changed
+      # to the on_expire state if:
+      # - The item receives any command within the timed command duration.
+      # - The item is updated to a different state, even if it is then updated
+      #   back to the same state.
+      #
+      # For example, if you have a Switch on a timer and another rule sends
+      # a command to that item, even when it's commanded to the same state,
+      # the timer will be automatically canceled.
+      #
+      # Sending a different duration (for:) value for the timed
       # command will reschedule the timed command for that new duration.
       #
       module TimedCommand
@@ -107,7 +114,7 @@ module OpenHAB
               # no prior timed command
               on_expire ||= default_on_expire(command)
               super(command)
-              create_timed_command(duration: duration, on_expire: on_expire)
+              create_timed_command(command, duration: duration, on_expire: on_expire)
             else
               timed_command_details.mutex.synchronize do
                 if timed_command_details.resolution
@@ -116,7 +123,7 @@ module OpenHAB
                   # just create a new one
                   on_expire ||= default_on_expire(command)
                   super(command)
-                  create_timed_command(duration: duration, on_expire: on_expire)
+                  create_timed_command(command, duration: duration, on_expire: on_expire)
                 else
                   # timed command still pending; reset it
                   logger.trace "Outstanding Timed Command #{timed_command_details} encountered - rescheduling"
@@ -138,13 +145,13 @@ module OpenHAB
         private
 
         # Creates a new timed command and places it in the TimedCommand hash
-        def create_timed_command(duration:, on_expire:)
+        def create_timed_command(command, duration:, on_expire:)
           timed_command_details = TimedCommandDetails.new(item: self,
                                                           on_expire: on_expire,
                                                           mutex: Mutex.new)
 
           timed_command_details.timer = timed_command_timer(timed_command_details, duration)
-          cancel_rule = TimedCommandCancelRule.new(timed_command_details)
+          cancel_rule = TimedCommandCancelRule.new(command, timed_command_details)
           unmanaged_rule = Core.automation_manager.add_unmanaged_rule(cancel_rule)
           timed_command_details.rule_uid = unmanaged_rule.uid
           Core::Rules::Provider.current.add(unmanaged_rule)
@@ -189,16 +196,27 @@ module OpenHAB
         #
         # @!visibility private
         class TimedCommandCancelRule < org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
-          def initialize(timed_command_details)
+          def initialize(command, timed_command_details)
             super()
             @timed_command_details = timed_command_details
             # Capture rule name if known
             @thread_locals = ThreadLocal.persist
             self.name = "Cancel implicit timer for #{timed_command_details.item.name}"
-            self.triggers = [Rules::RuleTriggers.trigger(
-              type: Rules::Triggers::Changed::ITEM_STATE_CHANGE,
-              config: { "itemName" => timed_command_details.item.name }
-            )]
+            self.triggers = [
+              Rules::RuleTriggers.trigger(
+                type: Rules::Triggers::Changed::ITEM_STATE_CHANGE,
+                config: {
+                  "itemName" => timed_command_details.item.name,
+                  "previousState" => timed_command_details.item.format_command(command).to_s
+                }
+              ),
+              Rules::RuleTriggers.trigger(
+                type: Rules::Triggers::Command::ITEM_COMMAND,
+                config: {
+                  "itemName" => timed_command_details.item.name
+                }
+              )
+            ]
             self.visibility = Core::Rules::Visibility::HIDDEN
           end