openhab-jrubyscripting 5.0.0.rc10 → 5.0.0.rc11

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

@@ -30,8 +30,8 @@ module OpenHAB
         # @param [Config] config Rule configuration
         #
         # Constructor sets a number of variables, no further decomposition necessary
+        #
         def initialize(config)
-          # Metrics disabled because only setters are called or defaults set.
           super()
           set_name(config.name)
           set_description(config.description)
@@ -50,6 +50,8 @@ module OpenHAB
           @thread_locals = ThreadLocal.persist
           @cleanup_hooks = Set.new
           @listener = nil
+          debounce_settings = config.debounce_settings || { for: nil }
+          @debouncer = Debouncer.new(**debounce_settings)
         end
 
         #
@@ -58,30 +60,34 @@ module OpenHAB
         # @param [java.util.Map] mod map provided by openHAB rules engine
         # @param [java.util.Map] inputs map provided by openHAB rules engine containing event and other information
         #
-        #
         def execute(mod = nil, inputs = nil)
+          execute!(mod, inputs)
+        end
+
+        # @!visibility private
+        def on_removal(listener)
+          @cleanup_hooks << listener
+          listen_for_removal unless @listener
+        end
+
+        private
+
+        # This method gets called in rspec's SuspendRules as well
+        def execute!(mod, inputs)
           ThreadLocal.thread_local(**@thread_locals) do
             logger.trace { "Execute called with mod (#{mod&.to_string}) and inputs (#{inputs.inspect})" }
             logger.trace { "Event details #{inputs["event"].inspect}" } if inputs&.key?("event")
             trigger_conditions(inputs).process(mod: mod, inputs: inputs) do
               event = extract_event(inputs)
-              process_queue(create_queue(event), mod, event)
+              @debouncer.call { process_queue(create_queue(event), mod, event) }
             end
           rescue Exception => e
-            raise if defined?(::RSpec)
+            raise if defined?(::RSpec) && ::RSpec.current_example.example_group.propagate_exceptions?
 
             @run_context.send(:logger).log_exception(e)
           end
         end
 
-        # @!visibility private
-        def on_removal(listener)
-          @cleanup_hooks << listener
-          listen_for_removal unless @listener
-        end
-
-        private
-
         def cleanup
           @cleanup_hooks.each(&:cleanup)
         end
@@ -180,17 +186,18 @@ module OpenHAB
         def check_guards(event:)
           return true if @guard.nil?
 
-          if @guard.should_run? event
-            return true if @between.nil?
-
+          unless @between.nil?
             now = Time.now
-            return true if @between.cover? now
-
-            logger.trace("Skipped execution of rule '#{name}' because the current time #{now} " \
-                         "is not between #{@between.begin} and #{@between.end}")
-          else
-            logger.trace("Skipped execution of rule '#{name}' because of guard #{@guard}")
+            unless @between.cover?(now)
+              logger.trace("Skipped execution of rule '#{name}' because the current time #{now} " \
+                           "is not between #{@between.begin} and #{@between.end}")
+              return false
+            end
           end
+
+          return true if @guard.should_run?(event)
+
+          logger.trace("Skipped execution of rule '#{name}' because of guard #{@guard}")
           false
         end
 

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

@@ -139,6 +139,9 @@ module OpenHAB
         # @return [Array] Of trigger definitions as passed in Ruby
         attr_reader :ruby_triggers
 
+        # @!visibility private
+        attr_reader :debounce_settings
+
         # @!visibility private
         Run = Struct.new(:block)
 
@@ -380,6 +383,30 @@ module OpenHAB
         #
         prop :enabled
 
+        #
+        # Returns all {Item Items} (or {GroupItem::Members GroupItem::Members}) referenced
+        # by the specified trigger types in this rule.
+        #
+        # @param [Symbol, Array<Symbol>] trigger_types Trigger types to search for dependencies
+        # @return [Array<Item, GroupItem::Members>]
+        #
+        # @example Ensure all dependencies have a state when executing a rule
+        #   rule do |rule|
+        #     changed Item1, Item2, Item3
+        #     only_if { rule.dependencies.all?(&:state?) }
+        #     run { FormulaItem.update(Item3.state - (Item1.state + Item2.state)) }
+        #   end
+        #
+        def dependencies(trigger_types = %i[changed updated])
+          trigger_types = Array.wrap(trigger_types)
+
+          ruby_triggers.flat_map do |t|
+            next [] unless trigger_types.include?(t.first)
+
+            t[1].select { |i| i.is_a?(Item) || i.is_a?(GroupItem::Members) }
+          end.uniq
+        end
+
         # @!group Guards
         #   Guards exist to only permit rules to run if certain conditions are
         #   satisfied. Think of these as declarative `if` statements that keep
@@ -388,8 +415,8 @@ module OpenHAB
         #
         #   ### Guard Combination
         #
-        #   {#only_if} and {#not_if} can be used on the same rule. Both must be
-        #   satisfied for a rule to execute.
+        #   Multiple guards can be used on the same rule. All must be satisfied
+        #   for a rule to execute.
         #
         #   @example
         #     rule "Set OutsideDimmer to 50% if LightSwitch turned on and OtherSwitch is OFF and Door is CLOSED" do
@@ -403,7 +430,7 @@ module OpenHAB
         #
         # @!method between(range)
         #
-        # Only execute rule if current time is between supplied time ranges.
+        # Only execute rule if the current time is between the supplied time ranges.
         #
         # If the range is of strings, it will be parsed to an appropriate time class.
         #
@@ -464,7 +491,7 @@ module OpenHAB
         #
         # @!method only_if
         #
-        # {only_if} allows rule execution when the block's is true and prevents it when it's false.
+        # Allows rule execution when the block's result is true and prevents it when it's false.
         #
         # @yieldparam [Core::Events::AbstractEvent] event The event data that is about to trigger the rule.
         # @yieldreturn [Boolean] A value indicating if the rule should run.
@@ -493,15 +520,13 @@ module OpenHAB
         #   end
         #
         prop_array(:only_if) do |item|
-          unless item.is_a?(Proc) || [item].flatten.all? { |it| it.respond_to?(:truthy?) }
-            raise ArgumentError, "Object passed to only_if must be a proc"
-          end
+          raise ArgumentError, "Object passed to only_if must be a proc" unless item.is_a?(Proc)
         end
 
         #
         # @!method not_if
         #
-        # {not_if} prevents execution of rules when the block's result is true and allows it when it's true.
+        # Prevents execution of rules when the block's result is true and allows it when it's true.
         #
         # @yieldparam [Core::Events::AbstractEvent] event The event data that is about to trigger the rule.
         # @yieldreturn [Boolean] A value indicating if the rule should _not_ run.
@@ -523,9 +548,187 @@ module OpenHAB
         #   end
         #
         prop_array(:not_if) do |item|
-          unless item.is_a?(Proc) || [item].flatten.all? { |it| it.respond_to?(:truthy?) }
-            raise ArgumentError, "Object passed to not_if must be a proc"
-          end
+          raise ArgumentError, "Object passed to not_if must be a proc" unless item.is_a?(Proc)
+        end
+
+        # rubocop:disable Layout/LineLength
+
+        #
+        # Waits until triggers have stopped firing for a period of time before executing the rule.
+        #
+        # It ignores triggers that are "bouncing around" (rapidly firing) by ignoring
+        # them until they have quiesced (stopped triggering for a while).
+        #
+        # ## Comparison Table
+        # | Guard          | Triggers Immediately | Description                                                                                                                                                                      |
+        # | -------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+        # | {debounce_for} | No                   | Waits until there is a minimum interval between triggers.                                                                                                                        |
+        # | {throttle_for} | No                   | Rate-limits the executions to a minimum interval, regardless of the interval between triggers. Waits until the end of the period before executing, ignores any leading triggers. |
+        # | {only_every}   | Yes                  | Rate-limits the executions to a minimum interval. Immediately executes the first trigger, then ignores subsequent triggers for the period.                                       |
+        #
+        # ## Timing Diagram
+        # The following timing diagram illustrates the difference between {debounce_for},
+        # {throttle_for}, and {only_every} guards:
+        #
+        # ```
+        # TIME INDEX ===>                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....X.XXXXXXXXXXX....X....."
+        # debounce_for 5    : "|......................X.|..............X....."
+        # debounce_for 5..5 : "|....X|....X.|....X....|....X|....X|....X....X"
+        # debounce_for 5..6 : "|.....X...|.....X.|....X.|.....X|.....X.|....X"
+        # debounce_for 5..7 : "|......X..|......X|....X.|......X|......X....."
+        # debounce_for 5..8 : "|.......X.|.......X....|.......X|.......X....."
+        # debounce_for 5..20: "|...................X..|................X....."
+        # # throttle_for will fire every 5 intervals after the "first" trigger
+        # throttle_for 5    : "|....X|....X.|....X....|....X|....X|....X....."
+        # only_every 5      : "X.....X......X....X....X....X....X......X....."
+        #
+        # Triggers          : "X.X...X...X..XX.X.X..X...XXXXXXXXXXX.X..X.X..."
+        # debounce_for 5..44: "|...........................................X."
+        #
+        # # Notice above, triggers keep firing with intervals less than 5, so
+        # # debouncer keeps waiting, but puts a stop at 44 (the end of range).
+        # ```
+        #
+        # @param [Duration,Range] debounce_time The minimum interval between two consecutive
+        #   triggers before the rules are allowed to run.
+        #
+        #   When specified just as a Duration or an endless range, it sets the minimum interval
+        #   between two consecutive triggers before rules are executed. It will
+        #   wait endlessly unless this condition is met or an end of range was specified.
+        #
+        #   When the end of the range is specified, it sets the maximum amount of time to wait
+        #   from the first trigger before the rule will execute, even when triggers continue
+        #   to occur more frequently than the minimum interval.
+        #
+        #   When an equal beginning and ending values are given, it will behave just like
+        #   {throttle_for}.
+        #
+        # @return [void]
+        #
+        # @see throttle_for
+        # @see only_every
+        #
+        # @example Wait until item stopped changing for at least 1 minute before running the rule
+        #   rule do
+        #     changed Item1
+        #     debounce_for 1.minute
+        #     run { ... }
+        #   end
+        #
+        # @example Alert when door is open for a while
+        #   # Note: When combined with a state check (only_if), this becomes functionally
+        #   # equivalent to the changed duration feature.
+        #   rule "Door alert" do
+        #     changed Door_State
+        #     debounce_for 10.minutes
+        #     only_if { Door_State.open? }
+        #     run { notify("The Door has been open for 10 minutes!") }
+        #   end
+        #
+        def debounce_for(debounce_time)
+          idle_time = debounce_time.is_a?(Range) ? debounce_time.begin : debounce_time
+          debounce(for: debounce_time, idle_time: idle_time)
+        end
+        # rubocop:enable Layout/LineLength
+
+        #
+        # Rate-limits rule executions by delaying triggers and executing the last
+        # trigger within the given duration.
+        #
+        # When a new trigger occurs, it will hold the execution and start a fixed timer for
+        # the given duration. Should more triggers occur during this time, keep holding
+        # and once the wait time is over, execute the latest trigger.
+        #
+        # {throttle_for} will execute rules after it had waited
+        # for the given duration, regardless of how frequently the triggers were occuring.
+        # In contrast, {debounce_for} will wait until there is a minimum interval
+        # between two triggers.
+        #
+        # {throttle_for} is ideal in situations where regular status updates need to be made
+        # for frequently changing values. It is also useful when a rule responds to triggers
+        # from multiple related items that are updated at around the same time. Instead of
+        # executing the rule multiple times, {throttle_for} will wait for a pre-set amount
+        # of time since the first group of triggers occurred before executing the rule.
+        #
+        # @param [Duration] duration The minimum amount of time to wait inbetween rule
+        #   executions.
+        #
+        # @return [void]
+        #
+        # @see debounce_for
+        # @see only_every
+        #
+        # @example Perform calculations from multiple items
+        #   rule "Update Power Summary " do |rule|
+        #     changed Power_From_Solar, Power_Load, Power_From_Grid
+        #     throttle_for 1.second
+        #     only_if { rule.dependencies.all?(&:state?) } # make sure all items have a state
+        #     run do
+        #       msg = []
+        #       msg << Power_Load.state.negate.to_unit("kW").format("Load: %.2f %unit%")
+        #       msg << Power_From_Solar.state.to_unit("kW").format("PV: %.2f %unit%")
+        #       if Power_From_Grid.positive?
+        #         msg << Power_From_Grid.state.to_unit("kW").format("From Grid: %.1f %unit%")
+        #       else
+        #         msg << Power_From_Grid.state.negate.to_unit("kW").format("To Grid: %.1f %unit%")
+        #       end
+        #       Power_Summary.update(msg.join(", "))
+        #     end
+        #   end
+        #
+        def throttle_for(duration)
+          debounce(for: duration)
+        end
+
+        #
+        # Executes the rule then ignores subsequent triggers for a given duration.
+        #
+        # Additional triggers that occur within the given duration after the rule execution
+        # will be ignored. This results in executions happening only at the specified interval or
+        # more.
+        #
+        # Unlike {throttle_for}, this guard will execute the rule as soon as a new trigger
+        # occurs instead of waiting for the specified duration. This is ideal for triggers
+        # such as a door bell where the rule should run as soon as a new trigger is detected
+        # but ignore subsequent triggers if they occur too soon after.
+        #
+        # @param [Duration,:second,:minute,:hour,:day] interval The period during which
+        #   subsequent triggers are ignored.
+        # @return [void]
+        #
+        # @example Only allow executions every 10 minutes or more
+        #   rule "Aircon Vent Control" do
+        #     changed BedRoom_Temperature
+        #     only_every 10.minutes
+        #     run do
+        #       # Adjust BedRoom_Aircon_Vent
+        #     end
+        #   end
+        #
+        # @example Run only on the first update and ignore subsequent triggers for the next minute
+        #   # They can keep pressing the door bell as often as they like,
+        #   # but the bell will only ring at most once every minute
+        #   rule do
+        #     updated DoorBell_Button, to: "single"
+        #     only_every 1.minute
+        #     run { Audio.play_stream "doorbell.mp3" }
+        #   end
+        #
+        # @example Using symbolic duration
+        #   rule "Display update" do
+        #     updated Power_Usage
+        #     only_every :minute
+        #     run { Power_Usage_Display.update "Current power usage: #{Power_Usage.average_since(1.minute.ago)}" }
+        #   end
+        #
+        # @see debounce_for
+        # @see throttle_for
+        #
+        def only_every(interval)
+          interval = 1.send(interval) if %i[second minute hour day].include?(interval)
+          debounce(for: interval, leading: true)
         end
 
         # @!endgroup
@@ -541,7 +744,8 @@ module OpenHAB
           @rule_triggers = RuleTriggers.new
           @caller = caller_binding.eval "self"
           @ruby_triggers = []
-          @on_load_id = nil
+          @on_load = nil
+          @debounce_settings = nil
           enabled(true)
           tags([])
         end
@@ -680,8 +884,7 @@ module OpenHAB
         #    end
         def channel_linked(attach: nil)
           @ruby_triggers << [:channel_linked]
-          trigger("core.GenericEventTrigger", eventTopic: "openhab/links/*/added",
-                                              eventTypes: "ItemChannelLinkAddedEvent", attach: attach)
+          event("openhab/links/*/added", types: "ItemChannelLinkAddedEvent", attach: attach)
         end
 
         #
@@ -702,8 +905,7 @@ module OpenHAB
         #    end
         def channel_unlinked(attach: nil)
           @ruby_triggers << [:channel_linked]
-          trigger("core.GenericEventTrigger", eventTopic: "openhab/links/*/removed",
-                                              eventTypes: "ItemChannelLinkRemovedEvent", attach: attach)
+          event(topic: "openhab/links/*/removed", types: "ItemChannelLinkRemovedEvent", attach: attach)
         end
 
         #
@@ -976,6 +1178,8 @@ module OpenHAB
         # and on subsequent reloads on file modifications.
         # This is useful to perform initialization routines, especially when combined with other triggers.
         #
+        # @param [Duration] delay The amount of time to wait before executing the rule.
+        #   When nil, execute immediately.
         # @param [Object] attach Object to be attached to the trigger
         # @return [void]
         #
@@ -993,12 +1197,12 @@ module OpenHAB
         #     run { Security_Lights.on }
         #   end
         #
-        def on_load(attach: nil)
-          # prevent overwriting @on_load_id
-          raise ArgumentError, "on_load can only be used once within a rule" if @on_load_id
+        def on_load(delay: nil, attach: nil)
+          # prevent overwriting @on_load
+          raise ArgumentError, "on_load can only be used once within a rule" if @on_load
 
-          @on_load_id = SecureRandom.uuid
-          attachments[@on_load_id] = attach
+          @on_load = { module: SecureRandom.uuid, delay: delay }
+          attachments[@on_load[:module]] = attach
         end
 
         #
@@ -1165,6 +1369,61 @@ module OpenHAB
           end
         end
 
+        #
+        # Creates an item added trigger
+        #
+        # @param [Object] attach object to be attached to the trigger
+        # @return [void]
+        #
+        # @example
+        #    rule "item added" do
+        #      item_added
+        #      run do |event|
+        #        logger.info("#{event.item.name} added.")
+        #      end
+        #    end
+        def item_added(attach: nil)
+          @ruby_triggers << [:item_added]
+          event("openhab/items/*/added", types: "ItemAddedEvent", attach: attach)
+        end
+
+        #
+        # Creates an item removed trigger
+        #
+        # @param [Object] attach object to be attached to the trigger
+        # @return [void]
+        #
+        # @example
+        #    rule "item removed" do
+        #      item_removed
+        #      run do |event|
+        #        logger.info("#{event.item.name} removed.")
+        #      end
+        #    end
+        def item_removed(attach: nil)
+          @ruby_triggers << [:item_removed]
+          event("openhab/items/*/removed", types: "ItemRemovedEvent", attach: attach)
+        end
+
+        #
+        # Creates an item updated trigger
+        #
+        # @param [Object] attach object to be attached to the trigger
+        # @return [void]
+        #
+        # @example
+        #   rule "item updated" do
+        #     item_updated
+        #     run do |event|
+        #       logger.info("#{event.item.name} updated.")
+        #     end
+        #   end
+        #
+        def item_updated(attach: nil)
+          @ruby_triggers << [:item_updated]
+          event("openhab/items/*/updated", types: "ItemUpdatedEvent", attach: attach)
+        end
+
         #
         # Creates a thing added trigger
         #
@@ -1180,8 +1439,7 @@ module OpenHAB
         #    end
         def thing_added(attach: nil)
           @ruby_triggers << [:thing_added]
-          trigger("core.GenericEventTrigger", eventTopic: "openhab/things/*/added",
-                                              eventTypes: "ThingAddedEvent", attach: attach)
+          event("openhab/things/*/added", types: "ThingAddedEvent", attach: attach)
         end
 
         #
@@ -1199,8 +1457,7 @@ module OpenHAB
         #    end
         def thing_removed(attach: nil)
           @ruby_triggers << [:thing_removed]
-          trigger("core.GenericEventTrigger", eventTopic: "openhab/things/*/removed",
-                                              eventTypes: "ThingRemovedEvent", attach: attach)
+          event("openhab/things/*/removed", types: "ThingRemovedEvent", attach: attach)
         end
 
         #
@@ -1210,17 +1467,39 @@ module OpenHAB
         # @return [void]
         #
         # @example
-        #    rule "thing updated" do
-        #      thing_updated
-        #      run do |event|
-        #        logger.info("#{event.thing.uid} updated.")
-        #      end
-        #    end
+        #   rule "thing updated" do
+        #     thing_updated
+        #     run do |event|
+        #       logger.info("#{event.thing.uid} updated.")
+        #     end
+        #   end
         #
         def thing_updated(attach: nil)
-          @ruby_triggers << [:thing_removed]
-          trigger("core.GenericEventTrigger", eventTopic: "openhab/things/*/updated",
-                                              eventTypes: "ThingUpdatedEvent", attach: attach)
+          @ruby_triggers << [:thing_updated]
+          event("openhab/things/*/updated", types: "ThingUpdatedEvent", attach: attach)
+        end
+
+        #
+        # Creates a trigger on events coming through the event bus
+        #
+        # @param [String] topic The topic to trigger on; can contain the wildcard `*`.
+        # @param [String, nil] source The sender of the event to trigger on.
+        #   Default does not filter on source.
+        # @param [String, Array<String>, nil] types Only subscribe to certain event types.
+        #   Default does not filter on event types.
+        # @return [void]
+        #
+        # @example
+        #   rule "thing updated" do
+        #     event("openhab/things/*/updated", types: "ThingUpdatedEvent")
+        #     run do |event|
+        #       logger.info("#{event.thing.uid} updated")
+        #     end
+        #   end
+        #
+        def event(topic, source: nil, types: nil, attach: nil)
+          types = types.join(",") if types.is_a?(Enumerable)
+          trigger("core.GenericEventTrigger", eventTopic: topic, eventSource: source, eventTypes: types, attach: attach)
         end
 
         #
@@ -1445,7 +1724,7 @@ module OpenHAB
             #<OpenHAB::DSL::Rules::Builder: #{uid}
             triggers=#{triggers.inspect},
             run blocks=#{run.inspect},
-            on_load=#{!@on_load_id.nil?},
+            on_load=#{!@on_load.nil?},
             Trigger Conditions=#{trigger_conditions.inspect},
             Trigger UIDs=#{triggers.map(&:id).inspect},
             Attachments=#{attachments.inspect}
@@ -1468,12 +1747,26 @@ module OpenHAB
           added_rule.actions.first.configuration.put("type", "application/x-ruby")
           added_rule.actions.first.configuration.put("script", script) if script
 
-          rule.execute(nil, { "module" => @on_load_id }) if @on_load_id
+          process_on_load { |module_id| rule.execute(nil, { "module" => module_id }) }
+
           added_rule
         end
 
         private
 
+        # Calls the on_load block, with a delay if specified
+        # @yield block to execute on load time
+        # @yieldparam [String] module The module ID that identifies this on_load event
+        def process_on_load
+          return unless @on_load
+
+          if @on_load[:delay]
+            after(@on_load[:delay]) { yield @on_load[:module] }
+          else
+            yield @on_load[:module]
+          end
+        end
+
         # delegate to the caller's logger
         def logger
           @caller.send(:logger)
@@ -1505,7 +1798,7 @@ module OpenHAB
         # @return [true,false] True if rule has triggers, false otherwise
         #
         def triggers?
-          @on_load_id || !triggers.empty?
+          !(@on_load.nil? && triggers.empty?)
         end
 
         #
@@ -1534,6 +1827,33 @@ module OpenHAB
           provider.add(unmanaged_rule)
           unmanaged_rule
         end
+
+        #
+        # Prevents or delays executions of rules to within a specified interval.
+        # Debounce handling is done after the from/to/command types are filtered, but before only_if/not_if
+        # guards.
+        #
+        # For a more detailed timing diagram, see {Debouncer}.
+        #
+        # Note the trailing edge debouncer delays the triggers so that they were postponed for the given interval after
+        # the first detection of the trigger.
+        #
+        # @param (see Debouncer#initialize)
+        #
+        # @return [void]
+        #
+        # @see Debouncer Debouncer class
+        # @see OpenHAB::DSL.debounce DSL.debounce method
+        # @see only_every
+        #
+        # @!visibility private
+        def debounce(for: 1.second, leading: false, idle_time: nil)
+          raise ArgumentError, "Debounce guard can only be specified once" if @debounce_settings
+
+          interval = binding.local_variable_get(:for)
+          # This hash structure must match the parameter signature for Debouncer.new
+          @debounce_settings = { for: interval, leading: leading, idle_time: idle_time }
+        end
       end
     end
   end