openhab-jrubyscripting 5.0.0.rc10 → 5.0.0.rc12

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)
 
@@ -355,7 +358,7 @@ module OpenHAB
         #
         # Set the rule's tags.
         #
-        # @param [String, Class, Array<String, Class>] tags
+        # @param [String, Symbol, Semantics::Tag] tags A list of tags to assign to the rule.
         # @return [void]
         #
         # @example
@@ -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
 
         #
@@ -899,7 +1101,10 @@ module OpenHAB
         #   :saturday,
         #   :sunday] value
         #   When to execute rule.
-        # @param [LocalTime, String, nil] at What time of day to execute rule
+        # @param [LocalTime, String, Core::Items::DateTimeItem, nil] at What time of day to execute rule
+        #   If `value` is `:day`, `at` can be a {Core::Items::DateTimeItem DateTimeItem}, and
+        #   the trigger will run every day at the (time only portion of) current state of the
+        #   item. If the item is {NULL} or {UNDEF}, the trigger will not run.
         # @param [Object] attach Object to be attached to the trigger
         # @return [void]
         #
@@ -955,11 +1160,23 @@ module OpenHAB
         #     run { logger.info "Happy Valentine's Day!" }
         #   end
         #
+        # @example
+        #   rule "Every day at sunset" do
+        #     every :day, at: Sunset_Time
+        #     run { logger.info "It's getting dark" }
+        #   end
+        #
         def every(value, at: nil, attach: nil)
           return every(java.time.MonthDay.parse(value), at: at, attach: attach) if value.is_a?(String)
 
           @ruby_triggers << [:every, value, { at: at }]
 
+          if value == :day && at.is_a?(Item)
+            raise ArgumentError, "Attachments are not supported with dynamic datetime triggers" unless attach.nil?
+
+            return trigger("timer.DateTimeTrigger", itemName: at.name, timeOnly: true)
+          end
+
           cron_expression = case value
                             when Symbol then Cron.from_symbol(value, at)
                             when Duration then Cron.from_duration(value, at)
@@ -976,6 +1193,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 +1212,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 +1384,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 +1454,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 +1472,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 +1482,69 @@ 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
+
+        #
+        # Creates a trigger based on the time stored in a {DateTimeItem}
+        #
+        # The trigger will dynamically update any time the state of the item
+        # changes. If the item is {NULL} or {UNDEF}, the trigger will not run.
+        #
+        # @param [Item, String, Symbol] item The item (or it's name)
+        # @return [void]
+        #
+        # @example
+        #   rule "say hello when the kids get home from school" do
+        #     at HomeFromSchool_Time
+        #     run do
+        #       KitchenEcho_TTS << "hi kids! how was school?"
+        #     end
+        #   end
+        #
+        #   rule "set home from school time" do
+        #     on_load
+        #     every :day, at: "5:00am" do
+        #     run do
+        #       HomeFromSchool_Time.ensure.update(school_day? ? LocalTime.parse("3:30pm") : NULL)
+        #     end
+        #   end
+        #
+        def at(item)
+          item = item.name if item.is_a?(Item)
+          trigger("timer.DateTimeTrigger", itemName: item.to_s)
         end
 
         #
@@ -1445,7 +1769,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 +1792,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 +1843,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 +1872,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