DSL: add ensure_timed_commands and ensure_timed_commands!. Make TimedCommand return nil when a timer isn't started.

lib/openhab/dsl.rb

@@ -666,7 +666,7 @@ def ensure_states!(active: true)
  end
 
  #
- # Global method that takes a block and for the duration of the block
+ # Global method that takes a block and for the duration of the block,
  # all commands sent will check if the item is in the command's state
  # before sending the command. This also applies to updates.
  #
@@ -717,6 +717,68 @@ def ensure_states
  ensure_states!(active: old)
  end
 
+ #
+ # Permanently set the _default_ `only_when_ensured` to true for {Items::TimedCommand TimedCommand}s
+ # for the current thread.
+ #
+ # When `only_when_ensured` is true, the timer in a timed command will only be started if the item's
+ # current state is not the same as the command.
+ #
+ # The option `only_when_ensured` can still be overridden by passing the `only_when_ensured` argument to
+ # a timed command.
+ #
+ # @note This method is only intended for use at the top level of rule
+ # scripts. If it's used within library methods, or hap-hazardly within
+ # rules, things can get very confusing because the prior state won't be
+ # properly restored.
+ #
+ # @param [Boolean] default Whether to set the default for `only_when_ensured` option to true.
+ # @return [Boolean] The previous ensure_timed_commands setting.
+ #
+ # @example Make `only_when_ensured`: true the default for the rest of the script
+ # # The default is `only_when_ensured`: false, so the timer will start regardless of the item's current state
+ # Item.ensure.command 50, for: 5.minutes
+ #
+ # ensure_timed_commands!
+ #
+ # # From now, the default is `only_when_ensured`: true,
+ # # so the timer will only start if the item's current state is different
+ # Item.command 50, for: 5.minutes
+ #
+ # # It can still be overridden by passing `only_when_ensured: false`
+ # Item.command 50, for: 5.minutes, only_when_ensured: false
+ #
+ # @see Items::TimedCommand TimedCommand
+ #
+ def ensure_timed_commands!(default: true)
+ old = Thread.current[:openhab_ensure_timed_commands]
+ Thread.current[:openhab_ensure_timed_commands] = default
+ old
+ end
+
+ #
+ # Global method that takes a block and for the duration of the block,
+ # all timed commands will default to `only_when_ensured`: true
+ #
+ # @example
+ # ensure_timed_commands do
+ # # `only_when_ensured` defaults to true for all timed commands inside the block
+ # Item.on for: 5.minutes
+ #
+ # # It does not affect non timed-commands
+ # # so a call to {ensure} still needs to be done when required
+ # Item2.ensure.on
+ # end
+ #
+ # @see Items::TimedCommand TimedCommand
+ #
+ def ensure_timed_commands
+ old = ensure_timed_commands!
+ yield
+ ensure
+ ensure_timed_commands!(default: old)
+ end
+
  #
  # Sets a thread local variable to set the default persistence service
  # for method calls inside the block
@@ -1088,6 +1150,8 @@ def try_parse_time_like(string)
  # Provide access to the script context / variables
  # see OpenHAB::DSL::Rules::AutomationRule#execute!
  #
+ #
+ #
  # @!visibility private
  ruby2_keywords def method_missing(method, *args)
  return super unless args.empty? && !block_given?

lib/openhab/dsl/items/timed_command.rb

@@ -89,12 +89,17 @@ class << self
  # @param [Command] command to send to object
  # @param [Duration] for duration for item to be in command state
  # @param [Command] on_expire Command to send when duration expires
- # @param [true, false] only_when_ensured if true, only start the timed command if the command was ensured
+ # @param [true, false, nil] only_when_ensured
+ # - When `true`, only start the timed command if the command was ensured.
+ # - When `false`, the timed command will be started regardless of the prior state of the item, even when
+ # {OpenHAB::DSL.ensure_timed_commands ensure_timed_commands} is in effect.
+ # - When `nil`, the timed command will be started unless
+ # {OpenHAB::DSL.ensure_timed_commands ensure_timed_commands} is in effect.
  # @yield If a block is provided, `on_expire` is ignored and the block
  # is expected to set the item to the desired state or carry out some
  # other action.
  # @yieldparam [TimedCommandDetails] timed_command
- # @return [self]
+ # @return [self, nil] self if the timer was started or extended, nil if the timer was not started.
  #
  # @example
  # Switch.command(ON, for: 5.minutes)
@@ -116,14 +121,18 @@ class << self
  # end
  # end
  #
- def command(command, for: nil, on_expire: nil, only_when_ensured: false, &block)
+ # @see DSL.ensure_timed_commands
+ # @see DSL.ensure_timed_commands!
+ #
+ def command(command, for: nil, on_expire: nil, only_when_ensured: nil, &block)
  duration = binding.local_variable_get(:for)
  return super(command) unless duration
 
  on_expire = block if block
 
  create_ensured_timed_command = proc do
  on_expire ||= default_on_expire(command)
+ only_when_ensured ||= Thread.current[:openhab_ensure_timed_commands]
  if only_when_ensured
  DSL.ensure_states do
  create_timed_command(command, duration: duration, on_expire: on_expire) if super(command)
@@ -134,7 +143,7 @@ def command(command, for: nil, on_expire: nil, only_when_ensured: false, &block)
  end
  end
 
- TimedCommand.timed_commands.compute(self) do |_key, timed_command_details|
+ timed_command = TimedCommand.timed_commands.compute(self) do |_key, timed_command_details|
  if timed_command_details.nil?
  # no prior timed command
  create_ensured_timed_command.call
@@ -160,7 +169,7 @@ def command(command, for: nil, on_expire: nil, only_when_ensured: false, &block)
  end
  end
 
- self
+ Core::Items::Proxy.new(self) if timed_command
  end
 
  private

lib/openhab/dsl/thread_local.rb

@@ -13,6 +13,7 @@ module ThreadLocal
  KNOWN_KEYS = %i[
  openhab_context
  openhab_ensure_states
+ openhab_ensure_timed_commands
  openhab_holiday_file
  openhab_persistence_service
  openhab_providers

spec/openhab/dsl/items/timed_command_spec.rb

@@ -31,64 +31,134 @@
  expect(item.state).to eq 0
  end
 
- it "can activate only when ensured" do
- commanded = false
- received_command(item) { commanded = true }
-
- if commanded # This won't execute because it's only for self documentation
- # First check our assumptions of the behavior without `only_when_ensured`
- # Possibly unnecessary because such behavior is already tested in other specs
- # but nice to have here for clarity
- #
- # ********
- # first without ensure
- item.update 7
- item.command(7, for: 1.second, on_expire: 0)
- expect(commanded).to be true
+ it "returns `self` (wrapped in a proxy)" do
+ expect(item.command(7, for: 1.seconds)).to be item
+ end
 
+ context "with `only_when_ensured` option" do
+ it "can activate only when ensured" do
  commanded = false
- time_travel_and_execute_timers(2.seconds)
- expect(commanded).to be true
- expect(item.state).to eq 0
+ received_command(item) { commanded = true }
+
+ if commanded # This won't execute because it's only for self documentation
+ # First check our assumptions of the behavior without `only_when_ensured`
+ # Possibly unnecessary because such behavior is already tested in other specs
+ # but nice to have here for clarity
+ #
+ # ********
+ # first without ensure
+ item.update 7
+ item.command(7, for: 1.second, on_expire: 0)
+ expect(commanded).to be true
+
+ commanded = false
+ time_travel_and_execute_timers(2.seconds)
+ expect(commanded).to be true
+ expect(item.state).to eq 0
+
+ # ********
+ # now with ensure (but still without `only_when_ensured`)
+ item.update(7)
+ commanded = false
+ item.ensure.command(7, for: 1.second, on_expire: 0)
+ expect(commanded).to be false
+
+ commanded = false
+
+ # the timed command still executes even though the command was ensured
+ time_travel_and_execute_timers(2.seconds)
+ expect(commanded).to be true
+ expect(item.state).to eq 0
+ end
 
  # ********
- # now with ensure (but still without `only_when_ensured`)
+ # now try it with `only_when_ensured`
  item.update(7)
  commanded = false
- item.ensure.command(7, for: 1.second, on_expire: 0)
+ item.command(7, for: 1.second, on_expire: 0, only_when_ensured: true)
+ expect(commanded).to be false
+
+ time_travel_and_execute_timers(2.seconds)
  expect(commanded).to be false
+ # The difference is here: the timer didn't even start, so the state didn't change to `on_expire` state
+ expect(item.state).to eq 7
 
+ # ********
+ # calling ensure explicitly should still work
+ item.update(7) # not necessary but for clarity
  commanded = false
+ item.ensure.command(7, for: 1.second, on_expire: 0, only_when_ensured: true)
+ expect(commanded).to be false
 
- # the timed command still executes even though the command was ensured
  time_travel_and_execute_timers(2.seconds)
- expect(commanded).to be true
- expect(item.state).to eq 0
+ expect(commanded).to be false
+ # The difference is here: the timer didn't even start, so the state didn't change to `on_expire` state
+ expect(item.state).to eq 7
  end
 
- # ********
- # now try it with `only_when_ensured`
- item.update(7)
- commanded = false
- item.command(7, for: 1.second, on_expire: 0, only_when_ensured: true)
- expect(commanded).to be false
+ it "returns self when the timer was started" do
+ item.update(0)
+ result = item.command(7, for: 1.second, only_when_ensured: true)
+ expect(result).to be item
+ end
 
- time_travel_and_execute_timers(2.seconds)
- expect(commanded).to be false
- # The difference is here: the timer didn't even start, so the state didn't change to `on_expire` state
- expect(item.state).to eq 7
+ it "returns nil when the timer was not started" do
+ item.update(0)
+ result = item.command(0, for: 1.second, only_when_ensured: true)
+ expect(result).to be_nil
+ end
+ end
 
- # ********
- # calling ensure explicitly should still work
- item.update(7) # not necessary but for clarity
- commanded = false
- item.ensure.command(7, for: 1.second, on_expire: 0, only_when_ensured: true)
- expect(commanded).to be false
+ describe "#ensure_timed_commands!" do
+ around do |example|
+ ensure_timed_commands!
+ example.run
+ ensure
+ ensure_timed_commands!(default: false)
+ end
 
- time_travel_and_execute_timers(2.seconds)
- expect(commanded).to be false
- # The difference is here: the timer didn't even start, so the state didn't change to `on_expire` state
- expect(item.state).to eq 7
+ it "makes `only_when_ensured` defaults to true for all timed commands" do
+ commanded = false
+ received_command(item) { commanded = true }
+
+ item.update(7)
+ # only_when_ensured is not specified in this call, but it should now defaults to true
+ item.command(7, for: 1.second, on_expire: 0)
+ expect(commanded).to be false
+
+ time_travel_and_execute_timers(2.seconds)
+ expect(commanded).to be false
+ # check that the timer didn't even start, so the state didn't change to `on_expire` state
+ expect(item.state).to eq 7
+ end
+ end
+
+ describe "#ensure_timed_commands" do
+ it "only takes effect inside the block" do
+ commanded = false
+ received_command(item) { commanded = true }
+
+ ensure_timed_commands do
+ item.update(7)
+ # only_when_ensured is not specified in this call, but it should now defaults to true
+ item.command(7, for: 1.second, on_expire: 0)
+ expect(commanded).to be false
+
+ time_travel_and_execute_timers(2.seconds)
+ expect(commanded).to be false
+ # check that the timer didn't even start, so the state didn't change to `on_expire` state
+ expect(item.state).to eq 7
+ end
+
+ # After the block, it shoult not default to true anymore
+ item.update(7)
+ commanded = false
+ item.command(7, for: 1.second, on_expire: 0)
+ expect(commanded).to be true
+
+ time_travel_and_execute_timers(2.seconds)
+ expect(item.state).to eq 0
+ end
  end
 
  context "with SwitchItem" do